> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.net/llms.txt
> Use this file to discover all available pages before exploring further.

# bunny sandbox

> Create and manage on-demand cloud sandbox environments backed by Bunny Magic Containers.

`bunny sandbox` manages on-demand cloud sandbox environments backed by [Bunny Magic Containers](/magic-containers). Each sandbox is a fully isolated Ubuntu container with Node.js, Bun, Python, and Claude Code pre-installed. A 10 GB persistent volume is mounted at `/workplace`, your default working directory.

Claude Code is pre-installed but needs your own Anthropic credentials before it can do anything: pass an API key at create time (prefer `--env-file .env` so the key stays out of your shell history), or run `claude` inside the sandbox and complete the login prompt it prints. Both survive restarts and redeploys: baked env vars live on the container, and the login flow writes to `/workplace/.claude` on the persistent volume.

Sandbox credentials (app ID, SSH endpoint, agent token) are stored in the CLI's local config file (`~/.config/bunnynet.json` by default) so you can reconnect without re-creating.

***

## `bunny sandbox create`

Create and start a new sandbox. Waits for the container's SSH port to become reachable before returning.

<CodeGroup>
  ```bash Command (create) theme={null}
  # Create a sandbox with the default name "sandbox"
  bunny sandbox create

  # Create a named sandbox
  bunny sandbox create my-sandbox

  # Create in a specific region
  bunny sandbox create my-sandbox --region NY

  # Bake in environment variables (persisted for the sandbox's lifetime)
  bunny sandbox create my-sandbox -e NODE_ENV=production -e PORT=8080
  bunny sandbox create my-sandbox --env-file .env

  # Give Claude Code your Anthropic API key at create time (.env holds ANTHROPIC_API_KEY)
  bunny sandbox create my-sandbox --env-file .env
  ```

  ```text Response (create) theme={null}
  Sandbox "my-sandbox" is ready.
    App ID: Ab3xK9mPq2wR7nL
    SSH:    203.0.113.42:8023

  Run commands with: bunny sandbox exec my-sandbox <command>
  ```
</CodeGroup>

| Flag         | Alias | Description                                        | Default |
| ------------ | ----- | -------------------------------------------------- | ------- |
| `--region`   |       | Region ID to deploy in (e.g. `AMS`, `NY`, `LA`, …) | `AMS`   |
| `--env`      | `-e`  | Environment variable as `KEY=VALUE` (repeatable)   |         |
| `--env-file` |       | Load environment variables from a dotenv file      |         |

Variables set at creation are baked into the container and persist across restarts. Values from `--env` override those loaded from `--env-file`. To change them later, use [`bunny sandbox env`](#bunny-sandbox-env).

Once ready, the output shows the app ID and SSH address. Public URLs come later via [`bunny sandbox url add`](#bunny-sandbox-url-add).

## `bunny sandbox list`

List all sandboxes saved in your local config.

<CodeGroup>
  ```bash Command (list) theme={null}
  bunny sandbox list
  bunny sandbox ls          # alias
  ```

  ```text Response (list) theme={null}
   Name        App ID           SSH
   my-sandbox  Ab3xK9mPq2wR7nL  203.0.113.42:8023
  ```
</CodeGroup>

## `bunny sandbox delete`

Delete a sandbox and permanently destroy the underlying Magic Containers app.

<CodeGroup>
  ```bash Command (delete) theme={null}
  bunny sandbox delete my-sandbox

  # Skip the confirmation prompt
  bunny sandbox delete my-sandbox --force
  bunny sandbox rm my-sandbox -f   # alias
  ```

  ```text Response (delete) theme={null}
  Delete sandbox "my-sandbox" (app Ab3xK9mPq2wR7nL)? (y/N) y
  Sandbox "my-sandbox" deleted.
  ```
</CodeGroup>

| Flag      | Alias | Description              | Default |
| --------- | ----- | ------------------------ | ------- |
| `--force` | `-f`  | Skip confirmation prompt | `false` |

## `bunny sandbox exec`

Run a shell command inside a sandbox over SSH. Defaults to `/workplace` as the working directory.

<CodeGroup>
  ```bash Command (exec) theme={null}
  # Run a command
  bunny sandbox exec my-sandbox ls -la

  # Run in a different directory
  bunny sandbox exec my-sandbox --cwd /tmp env

  # Pipe-friendly: exit code is propagated
  bunny sandbox exec my-sandbox -- cat /etc/os-release

  # Inject temporary environment variables for this command only
  bunny sandbox exec my-sandbox --env DEBUG=1 -- node app.js
  bunny sandbox exec my-sandbox --env-file .env -- printenv

  # Give up after 30 seconds (exit code 124)
  bunny sandbox exec my-sandbox --timeout 30 -- bun run build
  ```

  ```text Response (exec) theme={null}
  total 16
  drwxr-xr-x 3 root root 4096 Jul 16 09:12 .
  drwxr-xr-x 1 root root 4096 Jul 16 09:10 ..
  -rw-r--r-- 1 root root 1254 Jul 16 09:12 app.js
  drwxr-xr-x 2 root root 4096 Jul 16 09:11 src
  ```
</CodeGroup>

The command's stdout and stderr stream to your terminal unchanged, and its exit code is propagated, so `exec` works in scripts and pipes.

| Flag         | Alias | Description                                                     | Default      |
| ------------ | ----- | --------------------------------------------------------------- | ------------ |
| `--cwd`      |       | Working directory inside the sandbox                            | `/workplace` |
| `--env`      |       | Environment variable as `KEY=VALUE` (repeatable)                |              |
| `--env-file` |       | Load environment variables from a dotenv file                   |              |
| `--timeout`  |       | Close the SSH connection and exit `124` after this many seconds |              |

Variables passed here apply only to that single command and are **not** persisted. For persistent variables, use [`bunny sandbox env`](#bunny-sandbox-env).

## `bunny sandbox cp`

Copy a file between your machine and a sandbox over SFTP. Exactly one of the two paths must reference a sandbox as `<sandbox>:<path>`; the other is a local path. Remote paths follow the same rules as elsewhere: relative paths resolve against `/workplace`.

<CodeGroup>
  ```bash Command (cp) theme={null}
  # Upload a file into the sandbox
  bunny sandbox cp ./app.js my-sandbox:/workplace/app.js

  # Upload relative to /workplace
  bunny sandbox cp ./app.js my-sandbox:app.js

  # A trailing slash on the destination keeps the source filename
  bunny sandbox cp ./app.js my-sandbox:/workplace/src/

  # Download a file from the sandbox
  bunny sandbox cp my-sandbox:/workplace/out.log ./out.log

  # Download into an existing directory (keeps the source filename)
  bunny sandbox cp my-sandbox:/workplace/out.log ./logs/
  ```

  ```text Response (cp) theme={null}
  Copied ./app.js -> my-sandbox:/workplace/app.js
  ```
</CodeGroup>

Uploads preserve the local file's Unix mode (so executables stay executable). Only single files are supported; directory and sandbox-to-sandbox copies are not.

## `bunny sandbox files`

Manage files inside a sandbox over SFTP. A bare sandbox name targets `/workplace`; use `<sandbox>:<path>` for a specific directory (relative paths resolve against `/workplace`).

<CodeGroup>
  ```bash Command (files) theme={null}
  # List /workplace
  bunny sandbox files list my-sandbox
  bunny sandbox files ls my-sandbox    # alias

  # List a specific directory
  bunny sandbox files ls my-sandbox:/workplace/src
  bunny sandbox files ls my-sandbox:src

  # Machine-readable listing (name, type, size, mode)
  bunny sandbox files ls my-sandbox --output json
  ```

  ```text Response (files) theme={null}
   Name    Type       Size    Mode
   src     directory          755
   app.js  file       1.2 KB  644
   run.sh  file       182 B   755
  ```
</CodeGroup>

To copy files in and out, use [`bunny sandbox cp`](#bunny-sandbox-cp).

## `bunny sandbox ssh`

Open a full interactive SSH session. Drops you into a bash shell at `/workplace`. Type `exit` or press Ctrl-D to close.

```bash theme={null}
bunny sandbox ssh my-sandbox

# Set temporary environment variables for the session
bunny sandbox ssh my-sandbox -e DEBUG=1 --env-file .env
```

| Flag         | Alias | Description                                      | Default |
| ------------ | ----- | ------------------------------------------------ | ------- |
| `--env`      | `-e`  | Environment variable as `KEY=VALUE` (repeatable) |         |
| `--env-file` |       | Load environment variables from a dotenv file    |         |

Variables apply only to the session and are not persisted.

## `bunny sandbox url`

Manage public CDN endpoints for ports running inside a sandbox. Useful for exposing a dev server or API to the internet.

### `bunny sandbox url add`

Expose a container port as a public HTTPS endpoint. Waits until the URL is provisioned and prints it.

<CodeGroup>
  ```bash Command (url add) theme={null}
  # Expose port 3000 (endpoint named "port-3000")
  bunny sandbox url add my-sandbox 3000

  # Custom endpoint name
  bunny sandbox url add my-sandbox 8080 --label my-api
  ```

  ```text Response (url add) theme={null}
  Endpoint "port-3000" created.
    Port: 3000
    URL:  https://app-3000.b-cdn.net
  ```
</CodeGroup>

| Flag      | Description                   | Default       |
| --------- | ----------------------------- | ------------- |
| `--label` | Display name for the endpoint | `port-<port>` |

### `bunny sandbox url list`

List all user-created endpoints for a sandbox (built-in `api` and `ssh` endpoints are hidden).

<CodeGroup>
  ```bash Command (url list) theme={null}
  bunny sandbox url list my-sandbox
  bunny sandbox url ls my-sandbox    # alias
  ```

  ```text Response (url list) theme={null}
   ID                                    Name       Type  Port  URL
   Ab3xK9mPq2wR7nL-port-3000-Kj7mNp3qRx  port-3000  cdn   3000  https://app-3000.b-cdn.net
  ```
</CodeGroup>

### `bunny sandbox url delete`

Delete a public endpoint by name.

<CodeGroup>
  ```bash Command (url delete) theme={null}
  bunny sandbox url delete my-sandbox port-3000

  # Skip confirmation
  bunny sandbox url delete my-sandbox my-api --force
  bunny sandbox url rm my-sandbox my-api -f   # alias
  ```

  ```text Response (url delete) theme={null}
  Delete endpoint "port-3000" from sandbox "my-sandbox"? (y/N) y
  Endpoint "port-3000" deleted.
  ```
</CodeGroup>

| Flag      | Alias | Description              | Default |
| --------- | ----- | ------------------------ | ------- |
| `--force` | `-f`  | Skip confirmation prompt | `false` |

## `bunny sandbox env`

Manage a sandbox's **persistent** environment variables, the ones baked into the container. Unlike the temporary `--env` passed to `exec`/`ssh`, these survive across sessions. Changing them redeploys the sandbox with the new environment (running processes restart).

### `bunny sandbox env set`

Set one or more persistent variables, merging with the existing set.

<CodeGroup>
  ```bash Command (env set) theme={null}
  # Set a single variable
  bunny sandbox env set my-sandbox NODE_ENV=production

  # Set several at once
  bunny sandbox env set my-sandbox API_URL=https://api.example.com LOG_LEVEL=debug

  # Load from a dotenv file
  bunny sandbox env set my-sandbox --env-file .env
  ```

  ```text Response (env set) theme={null}
  Persisted 2 variable(s): API_URL, LOG_LEVEL
  The sandbox is redeploying to apply the change.
  ```
</CodeGroup>

| Flag         | Description                                   | Default |
| ------------ | --------------------------------------------- | ------- |
| `--env-file` | Load environment variables from a dotenv file |         |

### `bunny sandbox env list`

List the sandbox's persistent variables. The internal `AGENT_TOKEN` is hidden.

<CodeGroup>
  ```bash Command (env list) theme={null}
  bunny sandbox env list my-sandbox
  bunny sandbox env ls my-sandbox    # alias
  ```

  ```text Response (env list) theme={null}
   Name       Value
   LOG_LEVEL  debug
   NODE_ENV   production
  ```
</CodeGroup>

### `bunny sandbox env delete`

Remove one or more persistent variables. Names that are not set are reported and skipped; if none match, the command errors and nothing is redeployed.

<CodeGroup>
  ```bash Command (env delete) theme={null}
  bunny sandbox env delete my-sandbox NODE_ENV
  bunny sandbox env rm my-sandbox API_URL LOG_LEVEL    # alias
  bunny sandbox env unset my-sandbox API_URL           # alias
  ```

  ```text Response (env delete) theme={null}
  Removed 1 variable(s): NODE_ENV
  Not set (ignored): DEBUG
  The sandbox is redeploying to apply the change.
  ```
</CodeGroup>