sandbox
Create a sandbox directory pre-configured for omni.
Unless a specific path is provided, sandboxes are created under the directory configured by sandbox in the omni configuration (by default ~/sandbox). The command writes a fresh .omni.yaml file populated with the dependencies you pass on the command line, initializes the work directory metadata, trusts the new sandbox, and (when shell integration is enabled) emits a cd into the sandbox so you are dropped inside it even if the automatic omni up fails.
If the target already contains a git repository or an omni work directory, the user will be prompted before proceeding. If the target already contains an .omni.yaml file, net new dependencies will be appended.
Parameters
| Parameter | Required | Value type | Description |
|---|---|---|---|
--path, -p | no | directory path | Create the sandbox at an explicit path. The directory (and any missing parents) are created automatically if they do not exist. |
--name, -n | no | string | Name of the sandbox directory to create under the sandbox root. |
--allow-empty | no | null | Permit creating a sandbox without any dependencies. When omitted and no dependencies are provided, the command still succeeds but writes placeholder comments in .omni.yaml. |
dependencies… | no | string list | Dependencies to place under the up: section of the generated .omni.yaml. Individual entries can pin versions (for example go@1.21.1). |
Examples
# Create a sandbox under the configured sandbox root using an auto-generated name.
# The generated .omni.yaml contains the listed dependencies under the `up:` section.
omni sandbox node python
# Create a sandbox with a fixed name in the sandbox root.
omni sandbox --name hackday go@1.22.0 terraform@1.6.1
# Create a sandbox in an explicit directory.
omni sandbox --path ~/tmp/scratchpad rust@1.75.0
# Creating a sandbox also runs `omni up` automatically and trusts the new workdir.
# If the shell integration is active you will end up in the sandbox directory even
# when `omni up` fails, allowing you to investigate or rerun the command manually.