OpenShellA sandbox is the OpenShell data plane: a safe, private execution environment where an AI agent runs. Each sandbox combines runtime isolation with OpenShell policy controls that prevent unauthorized data access, credential exposure, and network exfiltration.
Create a sandbox with a single command. For example, to create a sandbox with Claude, run:
Every sandbox requires a gateway. Register or select one before running sandbox commands:
Set per-sandbox CPU and memory amounts with --cpu and --memory:
CPU values use Kubernetes-style quantities such as 500m, 1, or 2.5.
Memory values use byte quantities such as 512Mi, 4Gi, or 8G.
Docker and Podman apply these values as runtime limits. Kubernetes applies each value as both the request and the limit so the scheduler reserves the same amount the sandbox can use. The VM driver currently accepts these flags but does not change VM allocation.
To request GPU resources, add --gpu:
For Docker-backed sandboxes, GPU injection uses Docker CDI. If you enable Docker CDI after the gateway starts, restart the gateway so OpenShell can detect the updated Docker daemon capability.
Use --from to create a sandbox from the base image, another pre-built sandbox name, a local directory, or a container image:
Bare names such as base, openclaw, and ollama resolve to images under ghcr.io/nvidia/openshell-community/sandboxes. Set OPENSHELL_COMMUNITY_REGISTRY when you need to use an internal mirror.
Local directories and Dockerfiles require a local gateway because the CLI builds through the local Docker daemon. Use a registry image reference for remote gateways.
The base sandbox container is the default runtime image for standard OpenShell sandboxes unless the gateway overrides its default sandbox image. It is published as ghcr.io/nvidia/openshell-community/sandboxes/base:latest and maintained in the OpenShell Community repository.
The base container includes common development tooling, supported agent CLIs, and the default sandbox policy. Use it when you want a general-purpose agent environment without a workflow-specific image:
For default policy coverage by agent, refer to Default Policy. For the supported agent list, refer to Supported Agents.
Open an SSH session into a running sandbox:
Launch VS Code or Cursor directly into the sandbox workspace:
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.
Run a one-shot command inside a running sandbox without opening an interactive shell:
Pipe stdin into the command:
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 allocates a TTY automatically when both stdin and stdout are terminals. Force the behavior with --tty or disable it with --no-tty.
Attach labels when you create a sandbox to track ownership, environment, or workflow grouping:
List only the sandboxes that match a label selector:
Service forwarding makes a long-running process inside a sandbox reachable through a gateway-managed URL. Use it for development servers, notebooks, dashboards, or other services that keep listening after the sandbox starts. Run the service on loopback inside the sandbox, expose its port, then open the URL printed by OpenShell.
Expose a service that listens on loopback inside the sandbox:
Pass an optional service name to create a named service URL:
List exposed endpoints:
List endpoints for one sandbox:
Show or delete one endpoint:
Omit the service name to manage the unnamed endpoint:
Loopback gateways return local openshell.localhost URLs. Remote gateways return HTTPS URLs that require normal gateway authentication. For gateway service-domain configuration, refer to Manage Gateways.
List all sandboxes:
Filter the list by labels when you want a narrower view:
Use -o json or -o yaml for machine-readable output:
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:
Print only that policy YAML for scripting (same effective policy, no metadata):
Stream sandbox logs to monitor agent activity and diagnose policy decisions:
OpenShell Terminal combines sandbox status and live logs in a single real-time dashboard:
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.
Forward a local port to a running sandbox to access services inside it, such as a web server or database:
List and stop active forwards:
You can also forward a port at creation time with --forward:
Generate an SSH config entry for a sandbox so tools like VS Code Remote-SSH can connect directly:
Append the output to ~/.ssh/config or use --editor on sandbox create/sandbox connect for automatic setup.
Upload files from your host into the sandbox:
When the local path is a named directory, OpenShell preserves that basename at the destination, matching scp -r and cp -r. The example above creates /sandbox/src/src.
Download files from the sandbox to your host:
When the sandbox-side source is a single file, the destination follows cp-style placement: if the destination already exists as a directory or ends with /, the file lands inside it as <dest>/<basename>; otherwise the file is written at the exact destination path.
The CLI only allows sandbox-side sources that resolve inside the writable workspace (/sandbox). Paths that escape lexically (/etc/passwd, /sandbox/../etc/passwd) and paths that escape through a symlink (/sandbox/etc-link pointing at /etc) are both refused before any data is transferred.
You can also upload files at creation time with the --upload flag on
openshell sandbox create.
Deleting a sandbox stops all processes, releases resources, and purges injected credentials.
Every sandbox moves through a defined set of phases:
The gateway’s configured compute driver determines how OpenShell creates each sandbox. The CLI workflow stays the same across drivers: you create, connect to, inspect, and delete sandboxes through the gateway API.
For Docker, Podman, MicroVM, and Kubernetes behavior, refer to Sandbox Compute Drivers.
