Usage

Use this page as a command-oriented guide to day-to-day sbx operations. For scenario-based recommendations, see Workflow patterns.

Sign in

Sign in from a terminal:

$ sbx login

For scripts or CI runners where a browser isn't available, see CI and headless use.

Start, stop, and remove

The basic workflow is run to start, ls to check status, stop to pause, and rm to clean up:

$ sbx run claude                    # start an agent
$ sbx ls                            # see what's running
$ sbx stop my-sandbox               # pause it
$ sbx rm my-sandbox                 # delete it entirely

If the sandbox has an active session — an open attach, SSH connection, or in-flight SFTP transfer — sbx rm refuses unless you pass --force:

$ sbx rm --force my-sandbox

If you need a clean slate, remove the sandbox and run it again:

$ sbx stop my-sandbox
$ sbx rm my-sandbox
$ sbx run claude

Reconnect and name sandboxes

Sandboxes persist after the agent exits. Running the same workspace path again reconnects to the existing sandbox rather than creating another sandbox:

$ sbx run claude ~/my-project  # creates sandbox
$ sbx run claude ~/my-project  # reconnects to same sandbox

Use --name to give a sandbox an explicit identity:

$ sbx run claude --name my-project

Once a named sandbox exists, use --name to re-attach to it from any working directory, with or without the agent positional:

$ sbx run --name my-project        # re-attaches from anywhere
$ sbx run claude --name my-project # same, with agent confirmed

To run multiple sandboxes against the same workspace, give each a distinct name:

$ sbx run claude --name feature ~/my-project
$ sbx run claude --name spike ~/my-project

Create without attaching

sbx run creates the sandbox and attaches you to the agent. To create a sandbox in the background without attaching:

$ sbx create --name my-project claude .

Unlike run, create requires an explicit workspace path. Attach later with sbx run --name:

$ sbx run --name my-project

Run commands inside a sandbox

To get a shell inside a running sandbox, use sbx exec:

$ sbx exec -it <sandbox-name> bash

Interactive mode

Running sbx with no subcommands opens an interactive terminal dashboard:

$ sbx

The dashboard shows all your sandboxes as cards with live status, CPU, and memory usage. From here you can:

• Create a sandbox (c).
• Start or stop a sandbox (s).
• Attach to an agent session (Enter), same as sbx run.
• Open a shell inside the sandbox (x), same as sbx exec.
• Remove a sandbox (r).

The dashboard also includes a network governance panel where you can monitor outbound connections made by your sandboxes and manage network rules. Use tab to switch between the sandboxes panel and the network panel.

From the network panel you can browse connection logs, allow or block specific hosts, and add custom network rules. Press ? to see all keyboard shortcuts.

Git workspace modes

When your primary workspace is a Git repository, choose how the sandbox receives it when you create the sandbox:

• Direct mode is the default. The agent has read-write access to your working tree, and changes appear on your host immediately.
• Clone mode uses --clone. The agent edits a separate Git clone inside the sandbox. Its changes stay there until you fetch them or the agent pushes them. Your host repository is also available at /run/sandbox/source, but only with read access.

For guidance on branch strategy, fetching work from a sandbox, and parallel agent workflows, see Git workflows. For the security model behind each mode, see Workspace isolation.

Clone mode

To create a clone-mode sandbox, pass --clone when you run or create it:

$ sbx run --clone claude

You can also create the sandbox in the background and attach later:

$ sbx create --clone --name my-sandbox claude .
$ sbx run --name my-sandbox

Clone mode has a few create-time constraints:

• Clone mode is fixed at create time. To switch an existing sandbox to clone mode, remove it and recreate it with sbx create --clone.
• The clone follows whichever ref your host repository has checked out at create time. No branch is created automatically.
• The primary workspace must be a Git repository. Omit --clone for non-Git workspaces.
• Clone mode is rejected from inside a Git worktree other than the main one. The read-only bind mount can't resolve the worktree's .git pointer file. Run sbx create --clone from the main repository checkout instead.
• Removing a clone-mode sandbox drops the in-sandbox clone. Fetch or push any commits you want to keep before you remove it.

Multiple workspaces

You can mount extra directories into a sandbox alongside the main workspace. The first path is the primary workspace — the agent starts here, and the sandbox's in-container Git clone is populated from this directory if you use --clone. Extra workspaces are always mounted directly.

All workspaces appear inside the sandbox at their absolute host paths. Append :ro to mount an extra workspace read-only — useful for reference material or shared libraries the agent shouldn't modify:

$ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro

Each sandbox is completely isolated, so you can also run separate projects side-by-side. Remove unused sandboxes when you're done to reclaim disk space:

$ sbx run claude ~/project-a
$ sbx run claude ~/project-b
$ sbx rm <sandbox-name>       # when finished

Copying files between host and sandbox

Use sbx cp to copy files or directories between your host and a sandbox. This is useful for one-off files that aren't part of a mounted workspace, such as generated output, logs, or setup files.

$ sbx cp ./config.json my-sandbox:/home/user/
$ sbx cp my-sandbox:/home/user/output.log ./
$ sbx cp ./src/ my-sandbox:/home/user/src

One side of the copy must use SANDBOX:PATH. Copying directly between two sandboxes isn't supported.

Publish ports

Sandboxes are network-isolated — your browser or local tools can't reach a server running inside one by default. Use sbx ports to forward traffic from your host into a running sandbox.

$ sbx ports my-sandbox --publish 8080:3000   # host 8080 → sandbox port 3000
$ open http://localhost:8080

To let the OS pick a free host port instead of choosing one yourself:

$ sbx ports my-sandbox --publish 3000        # ephemeral host port
$ sbx ports my-sandbox                       # check which port was assigned

sbx ls shows active port mappings alongside each sandbox. sbx ports lists them in detail.

$ sbx ls
SANDBOX         AGENT   STATUS   PORTS                    WORKSPACE
my-sandbox      claude  running  127.0.0.1:8080->3000/tcp /home/user/proj

To stop forwarding a port:

$ sbx ports my-sandbox --unpublish 8080:3000

You can't publish ports at create time — there's no --publish flag on sbx run or sbx create, so publish them once the sandbox is running. For dev server and host-service recipes, see Local services.

What persists

While a sandbox exists, installed packages, Docker images, configuration changes, and command history all persist across stops and restarts. When you remove a sandbox, everything inside is deleted — only your workspace files remain on your host. To preserve a configured environment, create a custom template or use a kit.