Going further.

This page picks up where the quick start ends: a config root at ~/code/sandboxes with a web sandbox. The dashboard takes over the terminal. Scripts and agents use these plain commands instead, and their output is uncoloured when piped.

Start a sandbox

devsandbox run web           # prints the instance name: web
devsandbox exec -it web zsh  # a shell in the workspace
devsandbox exec web pnpm test

run builds the image (Features included), starts the database service, creates the container devsandbox-web with ../web mounted as the workspace, runs postCreateCommand, and returns once it’s up. The instance runs in the background.

What run, rebuild and start print, image build and lifecycle commands included, also goes to the instance’s build log. devsandbox logs --build web prints it, and --follow keeps printing until the instance is up or has failed. The previous one is kept next to it as build.1.log.

run, rebuild, start, stop and rm do their work in the host daemon, with your shell’s environment, and print it as it goes: closing the terminal doesn’t stop a build, and Ctrl-C still cancels it (a cancelled run is undone). Pass -d (--detach) to run, rebuild or start to get the instance name back as soon as it’s registered and leave the build running:

devsandbox rebuild -d --force web   # prints: web, the build goes on
devsandbox logs --build web --follow

exec runs in the workspace directory as the configured remoteUser, exits with the command’s own status, and takes -i / -t only for interactive shells. Any command that takes a name accepts an instance name, a sandbox name or the repo folder’s basename.

A second instance

Run the same sandbox again:

devsandbox run web   # prints: web-2
devsandbox ps        # both instances

web is already using your checkout, so web-2 gets its own git worktree in ~/code/sandboxes/.worktrees/web-2, on a fresh sandbox/web-2 branch. The two containers never share a working tree, which is the point when each one hosts a coding agent. Both reach the same global database.

Pick the name with --name, or check out an existing branch with --branch:

devsandbox run web --name fix-login --branch fix/login

From any directory

Commands read the devsandboxes.toml in the current directory. -C <dir> points any of them at another config root, so you don’t have to cd first:

devsandbox -C ~/code/sandboxes run web
devsandbox -C ~/code/sandboxes

On another machine

Sandboxes can also live on a server you reach over ssh. Register it once (machine add offers to install devsandbox there if it’s missing), then use its names like local ones:

devsandbox machine add me@my-server   # pick its config roots
devsandbox run api                    # defined only there: runs there, prints my-server/api
devsandbox exec api pnpm test         # over ssh, in the instance there
devsandbox stop my-server/web         # qualified, when `web` exists here too

See Other machines for what runs where.

Clean up

devsandbox stop web-2   # stopped, kept: `start web-2` resumes it
devsandbox rm web-2     # container, worktree and state entry gone
devsandbox gc           # reap services nothing references

rm also removes the instance’s isolated services, network and build log, and on a terminal asks before deleting the branch it created. Managed shell history is kept. Global services such as database outlive every rm until gc finds nothing referencing them.

Next steps

Source: site/src/content/docs/going-further.mdxEdit this page on GitHub(opens in a new tab)