devsandbox combines tools you’d otherwise wire together yourself into a single interface:
- devcontainer: images, Features and lifecycle commands, from the same standard VS Code uses.
- docker compose: the services a stack needs, one set per instance or shared by all.
- git worktrees: every repeat instance of a repo gets its own worktree and branch.
- Multiple machines: sandboxes on your other hosts, over ssh, in the same CLI and dashboard.
It runs on docker, podman or Apple container, with docker’s verbs: run, exec, ps, logs, rm.
One run gives you not a container but a whole sandbox, ready for an agent to work in.
Docker’s verbs, local defaults
A compose file and a devcontainer.json become one sandbox: the app’s container and the services it needs, the whole stack. Every sandbox you work on lives in one devsandboxes.toml; a second config is for another workspace, like personal projects next to work. Defaults are made for your laptop: a git worktree per instance, shared services and caches, your ssh-agent, ports tunneled on demand. Hand the config to your agent and it sets up the stack.
Diagram: on your machine, you ask your agent to set up an environment. It git clones the shop and billing repos into ~/code, then drives devsandbox with run --json and exec on your container runtime. There it brings up two sandboxes, each a whole stack, both defined in one config for your work workspace, ~/work/devsandboxes.toml: shop, with instance shop on its checkout and shop-2 on its own worktree, and a postgres per instance; and billing, with instance billing and a child instance billing-pr-42 on its own worktree of the PR branch fix/invoice-rounding, and a redis per instance. Across the sandbox boundary: ports tunneled to localhost with devsandbox port, your ssh-agent forwarded in so keys stay on the host, devsbd notify reaching you in the dashboard's Inbox and on the desktop, and, planned, credentials handed out on demand so tokens never live in a sandbox.
- Clone the repos. Your agent clones what the task needs side by side on your machine, like
~/code/apiand~/code/web. - Describe the stack. A
[sandbox.*]per repo in your workspace’sdevsandboxes.toml, with the services it needs and caches. Unknown keys are errors, so a typo fails fast. - Run, exec, report back.
devsandbox run --jsonreturns the new instance andexecruns in it. From inside,devsbd notifyreaches you when a human is needed.
What replaces what
| With docker | With devsandbox |
|---|---|
| A compose project per app | A sandbox per app, every one in your workspace’s devsandboxes.toml |
docker-compose.yml services |
[services.*]: one per instance on its own network, or scope = "global" for one shared by every sandbox |
devcontainer.json image, features, commands |
[sandbox.*]: the same image, Features and lifecycle commands, in TOML |
docker compose up a second time |
devsandbox run web again: a new instance, with its own containers and its own worktree and branch |
-p 3000:3000, decided up front |
devsandbox port web 3000, opened on demand, nothing restarts |
| Keys mounted or copied into the container | Your ssh-agent relayed: the container can sign, the keys stay on your host |
| Cache volumes you wire per project | caches = ["pnpm", "cargo"]: one store shared by every sandbox |
docker ps across everything |
devsandbox ps, or the dashboard: every instance, service, port and notification |
It builds on the devcontainer standard rather than replacing it: images, Features and lifecycle commands work as they do in VS Code, so the community’s existing setups carry over.
Other machines, over ssh
devsandbox machine add me@my-server registers a host you reach over ssh; its sandboxes then show next to yours and the CLI finds their names. Your keys don’t need to be there: with the machine’s agent on, your ssh-agent is relayed to it while you use it. See Other machines.
Next steps
Source: site/src/content/docs/vs-docker.mdxEdit this page on GitHub(opens in a new tab)