Manage sandboxes with the CLI

The cwsandbox command-line interface (CLI) manages existing CoreWeave sandboxes from your terminal. Use it to inspect sandboxes, run commands, retrieve logs, transfer files, manage file system snapshots, and clean up resources. Install the CLI as an optional extra of the Sandboxes Python client. Create sandboxes with the SDK before using the CLI. Follow the serverless quickstart or Use your own compute to create one.

Prerequisites

Before you begin, prepare the following:

An active Python 3.11 or later virtual environment with uv installed.
A credential for the account that owns your sandboxes. See Choose and get credentials for credential setup and required roles.
A running sandbox for command execution, interactive shells, log retrieval, file operations, and snapshot creation.

Install and authenticate

Choose the credential you used to create your sandboxes. Run the commands from one tab in your active virtual environment, replacing the credential placeholder with your key or token:

Forge API key
CoreWeave API access token

Install the cli and wandb extras, then select the W&B authentication strategy for your Forge API key:

uv pip install --upgrade 'cwsandbox[cli,wandb]'
export WANDB_API_KEY="WANDB_API_KEY_VALUE"
export CWSANDBOX_AUTH="wandb"
cwsandbox --help

Install the cli extra and select CoreWeave authentication:

uv pip install --upgrade 'cwsandbox[cli]'
export CWSANDBOX_API_KEY="API_ACCESS_TOKEN"
export CWSANDBOX_AUTH="coreweave_api_key"
cwsandbox --help

The help output lists the available commands. Keep the authentication variables set in the terminal where you run the remaining examples. CWSANDBOX_AUTH selects the credential strategy. The top-level --auth option overrides it for one invocation. For example, with Forge dependencies and credentials configured:

cwsandbox --auth wandb ls

To see the options for any command or subcommand, use --help:

cwsandbox exec --help
cwsandbox files read --help
cwsandbox snapshots create --help

Find your sandboxes

List sandboxes visible to your credential:

cwsandbox ls

Filter by status, or combine a status and a tag. Replace TAG with a tag attached to your sandboxes:

cwsandbox ls --status running
cwsandbox ls --status running --tag "TAG" --output json

The default table shows sandbox IDs, statuses, runners, and start times. --output json returns structured output. Repeat --tag or --runner-id to supply multiple filter values.

Inspect a sandbox

Replace SANDBOX_ID_VALUE with an ID from cwsandbox ls, and set it in your terminal:

export SANDBOX_ID="SANDBOX_ID_VALUE"
cwsandbox get "$SANDBOX_ID"
cwsandbox get "$SANDBOX_ID" --output json

The following examples use this variable. The details include the sandbox status, runner information, start time, and return code when available.

Run commands

Execute a command in a running sandbox. The command must be available in the sandbox image:

cwsandbox exec "$SANDBOX_ID" echo hello
cwsandbox exec "$SANDBOX_ID" python -c "print('hello')"

To set the remote working directory, pass --cwd before the remote command. Replace REMOTE_DIRECTORY with an existing directory in the sandbox:

cwsandbox exec "$SANDBOX_ID" --cwd "REMOTE_DIRECTORY" pwd

The CLI streams standard output and standard error to your local terminal. When the remote command completes normally, the CLI exits with its exit code.

Open an interactive shell

From a local terminal on macOS or Linux, open an interactive shell:

cwsandbox sh "$SANDBOX_ID"

The default shell is /bin/bash. Use --cmd to choose a different shell or an interactive program installed in the sandbox:

cwsandbox sh "$SANDBOX_ID" --cmd /bin/sh
cwsandbox sh "$SANDBOX_ID" --cmd "python -i"

The interactive shell requires a terminal for both standard input and standard output and isn’t supported on Windows. To leave a shell session, type exit or press Ctrl+D. Ctrl+C is forwarded to the remote process.

View logs

Retrieve logs from the sandbox’s main process:

cwsandbox logs "$SANDBOX_ID" --tail 100
cwsandbox logs "$SANDBOX_ID" --tail 100 --timestamps

Use --follow to stream new log output. Press Ctrl+C to stop following:

cwsandbox logs "$SANDBOX_ID" --follow

Use --since to filter logs by a timestamp. Replace 2026-09-10 09:00:00 with the start time you want. The CLI interprets a timestamp without a timezone as UTC:

cwsandbox logs "$SANDBOX_ID" --since "2026-09-10 09:00:00"

Logs contain standard output and standard error from the main process, which is the command used to create the sandbox. They don’t include output from cwsandbox exec. Sandboxes created with the default keep-alive command produce no log output. Log retrieval requires a running sandbox. Retrieve logs before stopping the sandbox. For more information, see Sandbox logging.

Read and write files

File operations require a running sandbox. To print a remote file to standard output, replace REMOTE_PATH with its path inside the sandbox:

cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH"

To download the file, add --output with a local destination. Replace LOCAL_PATH with the path where you want to save it:

cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH" --output "LOCAL_PATH"

To upload a file, supply the remote destination first and the existing local source file second:

cwsandbox files write "$SANDBOX_ID" "REMOTE_PATH" "LOCAL_PATH"

Manage file system snapshots

Snapshot creation requires a running sandbox configured with a file system snapshot mount. Your organization must be enabled for file system snapshots. Create a snapshot:

cwsandbox snapshots create "$SANDBOX_ID"

The command waits for the snapshot to become ready and prints its ID. To return without waiting for readiness and print the ID as JSON, use:

cwsandbox snapshots create "$SANDBOX_ID" --no-wait --output json

List snapshots, or filter to ready snapshots created from a specific sandbox:

cwsandbox snapshots list
cwsandbox snapshots list --source-sandbox-id "$SANDBOX_ID" --status ready

To inspect a snapshot, replace SNAPSHOT_ID_VALUE with its ID:

export SNAPSHOT_ID="SNAPSHOT_ID_VALUE"
cwsandbox snapshots get "$SNAPSHOT_ID"
cwsandbox snapshots get "$SNAPSHOT_ID" --output json

To delete a snapshot you no longer need, run:

cwsandbox snapshots delete "$SNAPSHOT_ID"

For snapshot requirements, supported storage, and restoring a sandbox with the SDK, see File system snapshots.

Stop or delete a sandbox

Stop a sandbox when you finish using it:

cwsandbox stop "$SANDBOX_ID"

To allow up to 30 seconds for graceful shutdown, use this alternative:

cwsandbox stop "$SANDBOX_ID" --graceful-shutdown-seconds 30

For a sandbox configured with a file system snapshot mount, capture a snapshot before stopping with this alternative:

cwsandbox stop "$SANDBOX_ID" --snapshot-on-stop

To delete a sandbox, run:

cwsandbox delete "$SANDBOX_ID"

For cleanup scripts, use --missing-ok so an already missing sandbox doesn’t cause an error:

cwsandbox delete "$SANDBOX_ID" --missing-ok

Sandboxes

Use sandboxes