--- title: page: Manage Sandboxes nav: Sandboxes description: Set up gateways, create sandboxes, and manage the full sandbox lifecycle. topics: - Generative AI - Cybersecurity tags: - Gateway - Sandboxing - AI Agents - Sandbox Management - CLI content: type: how_to difficulty: technical_beginner audience: - engineer - data_scientist --- # Manage Sandboxes This page covers creating sandboxes and managing them. For background on what sandboxes are and how isolation works, refer to [About Sandboxes](index.md). :::{important} 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: ```console $ 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 {doc}`manage-gateways` for deployment options and multi-gateway management. ### GPU Resources To request GPU resources, add `--gpu`: ```console $ 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: ```console $ 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](https://github.com/NVIDIA/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`. The following is an example of a fully specified creation command: ```console $ openshell sandbox create \ --name dev \ --provider my-claude \ --policy policy.yaml \ --upload \ -- claude ``` Additional `sandbox create` flags: | Flag | Purpose | |---|---| | `--no-keep` | Delete the sandbox automatically after the initial command exits | | `--forward ` | Forward a local port to the sandbox before running | | `--tty` / `--no-tty` | Force or disable pseudo-terminal allocation | | `--no-bootstrap` | Error if no gateway is available instead of auto-bootstrapping | | `--no-auto-providers` | Error if required providers are missing instead of prompting | ## Connect to a Sandbox Open an SSH session into a running sandbox: ```console $ openshell sandbox connect my-sandbox ``` Launch VS Code or Cursor directly into the sandbox workspace: ```console $ 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. ## Monitor and Debug List all sandboxes: ```console $ openshell sandbox list ``` Get detailed information about a specific sandbox: ```console $ openshell sandbox get my-sandbox ``` Stream sandbox logs to monitor agent activity and diagnose policy decisions: ```console $ 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: ```console $ openshell term ``` Use the terminal to spot blocked connections marked `action=deny` and inference interceptions marked `action=inspect_for_inference`. If a connection is blocked unexpectedly, add the host to your network policy. Refer to {doc}`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: ```console $ openshell forward start 8000 my-sandbox $ openshell forward start 8000 my-sandbox -d # run in background ``` List and stop active forwards: ```console $ openshell forward list $ openshell forward stop 8000 my-sandbox ``` :::{tip} You can also forward a port at creation time with `--forward`: ```console $ 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: ```console $ 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: ```console $ openshell sandbox upload my-sandbox ./src /sandbox/src ``` Download files from the sandbox to your host: ```console $ 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 Deleting a sandbox stops all processes, releases resources, and purges injected credentials. ```console $ openshell sandbox delete my-sandbox $ openshell sandbox delete --all ``` ## Next Steps - 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}`manage-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.