Manage sandboxes

Create sandboxes, connect to them, forward ports, transfer files, and manage the full sandbox lifecycle.

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

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). Start Docker and try again.

Create a sandbox

1. Run the create command

   Create a sandbox with a single command. To create a sandbox with Claude:

   openshell sandbox create -- claude
   

   Every sandbox requires a gateway. If none exists, the CLI auto-bootstraps a local gateway.

2. Wait for provisioning

   The sandbox moves through the Provisioning phase while the runtime sets up the environment, injects credentials, and applies your policy. When it reaches Ready, the agent process is active.

Choose your agent

Pass any supported agent as the trailing command:

openshell sandbox create -- claude
openshell sandbox create -- opencode
openshell sandbox create -- codex
openshell sandbox create -- copilot

Use the --from flag

Create a sandbox from a community package, a local directory, or a container image:

Community catalog

openshell sandbox create --from openclaw
openshell sandbox create --from ollama

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, refer to Community sandboxes.

Run on a remote gateway

If you plan to run sandboxes on a remote host or a cloud-hosted gateway, set up the gateway first, then create the sandbox as normal. Refer to Gateways for deployment options.

Request GPU resources

GPU passthrough is experimental. Expect rough edges and breaking changes.

Add --gpu to request GPU resources:

openshell sandbox create --gpu -- claude

NVIDIA drivers and the NVIDIA Container Toolkit must be installed on the host. The sandbox image must also include the appropriate GPU drivers and libraries.

Apply a policy at creation

Pass a policy YAML file with --policy:

openshell sandbox create --policy ./my-policy.yaml -- claude

To avoid passing --policy every time, set the OPENSHELL_SANDBOX_POLICY environment variable. Refer to Policies for the full policy workflow.

Forward a port at creation

openshell sandbox create --forward 8000 -- claude

Connect to a sandbox

SSH session

Open an SSH session into a running sandbox:

openshell sandbox connect my-sandbox

Editor (VS Code / Cursor)

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 manages SSH config automatically — it installs an OpenShell-managed SSH include file instead of adding entries to your main ~/.ssh/config.

SSH config

Generate an SSH config entry for tools like VS Code Remote-SSH:

openshell sandbox ssh-config my-sandbox

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

Monitor and debug

List all sandboxes:

openshell sandbox list

Get detailed information about a specific sandbox:

openshell sandbox get my-sandbox

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

Terminal UI

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

openshell term

Navigate with Tab to switch panels, j/k to move through lists, Enter to select, and : for command mode. Use it 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.

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

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

Providers

Supply API keys and tokens to sandboxes.

Policies

Control what the agent can access on the network and filesystem.

Community sandboxes

Use a pre-built environment from the community catalog.

GitHub sandbox tutorial

End-to-end walkthrough with scoped GitHub repo access.