Create and Manage Sandboxes#

This page walks you through the full sandbox lifecycle: creating, inspecting, connecting to, monitoring, and deleting sandboxes. For background on what sandboxes are and how the runtime works, refer to About Sandboxes.

Warning

Docker must be running before you create a 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#

Run a single command to create a sandbox and launch your agent:

$ openshell sandbox create -- claude

If you have an existing gateway, the sandbox is created in it. Otherwise, a gateway is created automatically.

A fully specified creation command might look like:

$ openshell sandbox create \
    --name dev \
    --provider my-claude \
    --policy policy.yaml \
    --upload \
    -- claude

Tip

Sandboxes created with openshell sandbox create stay running by default after the initial command or shell exits. Use --no-keep when you want the sandbox deleted automatically instead.

Create from a Community Sandbox or Custom Image#

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

$ openshell sandbox create --from openclaw

The CLI resolves the name 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.

You can also point --from at a local directory or a container image reference:

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

List and Inspect Sandboxes#

Check the status of your sandboxes and retrieve detailed information about individual ones.

List all sandboxes:

$ openshell sandbox list

Get detailed information about a specific sandbox:

$ openshell sandbox get my-sandbox

Connect to a Sandbox#

Access a running sandbox through an interactive SSH session or VS Code Remote-SSH.

Interactive SSH#

Open an SSH session into a running sandbox:

$ openshell sandbox connect my-sandbox

Open in a remote editor#

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.

View Logs#

Stream and filter sandbox logs to monitor agent activity and diagnose policy decisions.

Stream sandbox logs:

$ openshell logs my-sandbox

Use flags to filter and follow output:

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

Monitor Your Sandbox#

OpenShell Terminal is a real-time dashboard that combines sandbox status and live logs in a single view.

$ openshell term

The dashboard shows the following information.

  • Sandbox status: Name, phase, image, attached providers, age, and active port forwards.

  • Live log stream: Omutbound connections, policy decisions, and inference interceptions as they happen. Logs are labeled by source: sandbox (proxy and policy events) or gateway (lifecycle events).

Use the terminal to spot blocked connections (action=deny entries) and inference interceptions (action=inspect_for_inference entries). If a connection is blocked unexpectedly, add the host to your network policy — refer to Customize Sandbox Policies for the workflow.

Transfer Files#

Transfer files between your host machine and a running sandbox.

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

Note

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

Delete Sandboxes#

Remove sandboxes when they are no longer needed. Deleting a sandbox stops all processes, releases cluster resources, and purges injected credentials.

Delete a sandbox by name:

$ openshell sandbox delete my-sandbox

Delete all sandboxes in the active gateway:

$ openshell sandbox delete --all

Next Steps#

Explore related topics: