OpenShell/docs/sandboxes/create-and-manage.md

title, description, topics, tags, content

title	description	topics	tags	content
page nav Create and Manage Sandboxes Create and Manage	Create, inspect, connect to, monitor, transfer files, and delete OpenShell sandboxes.	Generative AI Cybersecurity	Sandboxing AI Agents Sandbox Management CLI	type difficulty audience how_to technical_beginner engineer data_scientist

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.

To request GPU resources explicitly, add --gpu:

$ openshell sandbox create --gpu -- claude

If no gateway is running, the auto-bootstrap path starts a GPU-enabled gateway first.

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 {doc}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

Images whose final name component contains gpu also trigger GPU sandbox requests automatically. For example, --from nvidia-gpu behaves like a GPU sandbox request even without --gpu.

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 {doc}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:

• To follow a complete end-to-end example, refer to the {doc}/tutorials/github-sandbox tutorial.
• To supply API keys or tokens, refer to {doc}providers.
• To control what the agent can access, refer to {doc}policies.
• To use a pre-built environment, refer to the {doc}community-sandboxes catalog.