Manage Sandboxes | NVIDIA OpenShell

This page covers creating sandboxes and managing them. For background on what sandboxes are and how isolation works, refer to About Sandboxes.

Docker must be running before you create a gateway or sandbox. If it is not, the CLI returns a connection-refused error (os error 61) without explaining the cause. Start Docker and try again.

Create a Sandbox

Create a sandbox with a single command. For example, to create a sandbox with Claude, run:

$ openshell sandbox create -- claude

Every sandbox requires a gateway. If you run openshell sandbox create without a gateway, the CLI auto-bootstraps a local gateway.

Remote Gateways

If you plan to run sandboxes on a remote host or a cloud-hosted gateway, set up the gateway first. Refer to Manage Gateways for deployment options and multi-gateway management.

GPU Resources

To request GPU resources, add --gpu:

$ openshell sandbox create --gpu -- claude

Custom Containers

Use --from to create a sandbox from a pre-built community package, a local directory, or a container image:

$ openshell sandbox create --from openclaw
$ openshell sandbox create --from ./my-sandbox-dir
$ openshell sandbox create --from my-registry.example.com/my-image:latest

The CLI resolves community names against the OpenShell Community catalog, pulls the bundled Dockerfile and policy, builds the image locally, and creates the sandbox. For the full catalog and how to contribute your own, refer to Community Sandboxes.

Connect to a Sandbox

Open an SSH session into a running sandbox:

$ openshell sandbox connect my-sandbox

Launch VS Code or Cursor directly into the sandbox workspace:

$ openshell sandbox create --editor vscode --name my-sandbox
$ openshell sandbox connect my-sandbox --editor cursor

When --editor is used, OpenShell keeps the sandbox alive and installs an OpenShell-managed SSH include file instead of cluttering your main ~/.ssh/config with generated host blocks.

Execute a Command in a Sandbox

Run a one-shot command inside a running sandbox without opening an interactive shell:

$ openshell sandbox exec -n my-sandbox -- ls -la /workspace

Pipe stdin into the command:

$ echo "hello" | openshell sandbox exec -n my-sandbox -- cat

The command’s exit code is propagated to the CLI, so exec works in scripts that check return codes.

Run an interactive shell with a TTY:

$ openshell sandbox exec -n my-sandbox --tty -- /bin/bash

OpenShell allocates a TTY automatically when both stdin and stdout are terminals. Force the behavior with --tty or disable it with --no-tty.

Flag	Purpose
`-n`, `--name`	Sandbox to target.
`--workdir`	Working directory for the command inside the sandbox.
`--timeout`	Command timeout in seconds. `0` disables the timeout.
`--tty`	Force TTY allocation.
`--no-tty`	Disable TTY allocation even when attached to a terminal.

Monitor and Debug

List all sandboxes:

$ openshell sandbox list

Get detailed information about a specific sandbox. The output lists Policy source (sandbox or global), Revision (the active policy’s row version for that source), and the formatted active policy YAML:

$ openshell sandbox get my-sandbox

Print only that policy YAML for scripting (same effective policy, no metadata):

$ openshell sandbox get my-sandbox --policy-only

Stream sandbox logs to monitor agent activity and diagnose policy decisions:

$ openshell logs my-sandbox

Flag	Purpose	Example
`--tail`	Stream logs in real time	`openshell logs my-sandbox --tail`
`--source`	Filter by log source	`--source sandbox`
`--level`	Filter by severity	`--level warn`
`--since`	Show logs from a time window	`--since 5m`

OpenShell Terminal combines sandbox status and live logs in a single real-time dashboard:

$ openshell term

Use the terminal to spot blocked connections marked action=deny and inference-related proxy activity. If a connection is blocked unexpectedly, add the host to your network policy. Refer to Policies for the workflow.

Port Forwarding

Forward a local port to a running sandbox to access services inside it, such as a web server or database:

$ openshell forward start 8000 my-sandbox
$ openshell forward start 8000 my-sandbox -d    # run in background

List and stop active forwards:

$ openshell forward list
$ openshell forward stop 8000 my-sandbox

You can also forward a port at creation time with --forward:

$ openshell sandbox create --forward 8000 -- claude

SSH Config

Generate an SSH config entry for a sandbox so tools like VS Code Remote-SSH can connect directly:

$ openshell sandbox ssh-config my-sandbox

Append the output to ~/.ssh/config or use --editor on sandbox create/sandbox connect for automatic setup.

Transfer Files

Upload files from your host into the sandbox:

$ openshell sandbox upload my-sandbox ./src /sandbox/src

Download files from the sandbox to your host:

$ openshell sandbox download my-sandbox /sandbox/output ./local

You can also upload files at creation time with the --upload flag on openshell sandbox create.

Delete Sandboxes

Deleting a sandbox stops all processes, releases resources, and purges injected credentials.

$ openshell sandbox delete my-sandbox

Next Steps

To follow a complete end-to-end example, refer to the Github Sandbox tutorial.
To supply API keys or tokens, refer to Manage Providers.
To control what the agent can access, refer to Policies.
To use a pre-built environment, refer to the Community Sandboxes catalog.