> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/OpenShell/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/concepts/architecture).

<Warning>
  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.
</Warning>

## Create a sandbox

<Steps>
  <Step title="Run the create command">
    Create a sandbox with a single command. To create a sandbox with Claude:

    ```bash theme={null}
    openshell sandbox create -- claude
    ```

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

  <Step title="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.
  </Step>
</Steps>

### Choose your agent

Pass any supported agent as the trailing command:

```bash theme={null}
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:

<CodeGroup>
  ```bash Community catalog theme={null}
  openshell sandbox create --from openclaw
  openshell sandbox create --from ollama
  ```

  ```bash Local directory theme={null}
  openshell sandbox create --from ./my-sandbox-dir
  ```

  ```bash Container image theme={null}
  openshell sandbox create --from my-registry.example.com/my-image:latest
  ```
</CodeGroup>

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, refer to [Community sandboxes](/sandboxes/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](/sandboxes/gateways) for deployment options.

### Request GPU resources

<Warning>
  GPU passthrough is experimental. Expect rough edges and breaking changes.
</Warning>

Add `--gpu` to request GPU resources:

```bash theme={null}
openshell sandbox create --gpu -- claude
```

NVIDIA drivers and the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) 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`:

```bash theme={null}
openshell sandbox create --policy ./my-policy.yaml -- claude
```

To avoid passing `--policy` every time, set the `OPENSHELL_SANDBOX_POLICY` environment variable. Refer to [Policies](/sandboxes/policies) for the full policy workflow.

### Forward a port at creation

```bash theme={null}
openshell sandbox create --forward 8000 -- claude
```

## Connect to a sandbox

<Tabs>
  <Tab title="SSH session">
    Open an SSH session into a running sandbox:

    ```bash theme={null}
    openshell sandbox connect my-sandbox
    ```
  </Tab>

  <Tab title="Editor (VS Code / Cursor)">
    Launch VS Code or Cursor directly into the sandbox workspace:

    ```bash theme={null}
    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`.
  </Tab>

  <Tab title="SSH config">
    Generate an SSH config entry for tools like VS Code Remote-SSH:

    ```bash theme={null}
    openshell sandbox ssh-config my-sandbox
    ```

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

## Monitor and debug

List all sandboxes:

```bash theme={null}
openshell sandbox list
```

Get detailed information about a specific sandbox:

```bash theme={null}
openshell sandbox get my-sandbox
```

Stream sandbox logs to monitor agent activity and diagnose policy decisions:

```bash theme={null}
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:

```bash theme={null}
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](/sandboxes/policies).

## Port forwarding

Forward a local port to a running sandbox to access services inside it, such as a web server or database:

```bash theme={null}
openshell forward start 8000 my-sandbox
openshell forward start 8000 my-sandbox -d    # run in background
```

List and stop active forwards:

```bash theme={null}
openshell forward list
openshell forward stop 8000 my-sandbox
```

## Transfer files

Upload files from your host into the sandbox:

```bash theme={null}
openshell sandbox upload my-sandbox ./src /sandbox/src
```

Download files from the sandbox to your host:

```bash theme={null}
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`.
</Note>

## Delete sandboxes

Deleting a sandbox stops all processes, releases resources, and purges injected credentials:

```bash theme={null}
openshell sandbox delete my-sandbox
```

## Next steps

<CardGroup cols={2}>
  <Card title="Providers" icon="key" href="/sandboxes/providers">
    Supply API keys and tokens to sandboxes.
  </Card>

  <Card title="Policies" icon="shield" href="/sandboxes/policies">
    Control what the agent can access on the network and filesystem.
  </Card>

  <Card title="Community sandboxes" icon="users" href="/sandboxes/community-sandboxes">
    Use a pre-built environment from the community catalog.
  </Card>

  <Card title="GitHub sandbox tutorial" icon="book" href="/tutorials/github-sandbox">
    End-to-end walkthrough with scoped GitHub repo access.
  </Card>
</CardGroup>