The problem
Two agents in one checkout trip over each other: one switches branch while the other is mid-edit, one’s git stash swallows the other’s work, both run the dev server on the same files. You want one working tree and one branch per agent, and a container for each so their processes stay apart too.
That is what repeat instances do. The first devsandbox run of a sandbox mounts the repo itself; every further instance of the same repo gets its own git worktree under the config dir, on its own branch, in its own container. Gitignored files a fresh checkout lacks, like .env, are copied or linked in for you.
Config
[sandbox.app]
folder = "../app" # your repo, next to this config dir
image = "node:22" # any image with the repo's toolchain
caches = ["npm"] # one npm cache for every instance
worktree-link = [".env"] # one .env, shared by every instance
# Your login and settings, from the host.
mounts = ["source=${localEnv:HOME}/,target=/root/,type=bind"]
containerEnv = { = "/root/" }
[sandbox.app.postCreateCommand] # once, when an instance is created
deps = "npm install"
agent = "npm install -g "[sandbox.app]
folder = "../app" # your repo, next to this config dir
image = "node:22" # any image with the repo's toolchain
caches = ["npm"] # one npm cache for every instance
worktree-link = [".env"] # one .env, shared by every instance
# Your login and settings, from the host.
mounts = ["source=${localEnv:HOME}/,target=/root/,type=bind"]
[sandbox.app.postCreateCommand] # once, when an instance is created
deps = "npm install"
agent = "npm install -g "On macOS keeps its login in the Keychain: run /login once in any instance.
Try it
One instance per task:
devsandbox run app --name fix-login # your checkout, ../app
devsandbox run app --name add-profile-pic --branch feat/profile-pic # its own worktree
devsandbox ps--name: the instance name.--branch: the branch name (defaultsandbox/<name>).
Start in each:
devsandbox exec -it fix-login
devsandbox exec -it add-profile-pic devsandbox exec -it fix-login
devsandbox exec -it add-profile-pic When a task is done, push its branch (ssh and git push) and remove the instance, container and worktree:
devsandbox rm add-profile-picHow it works
- Worktrees live in
.worktrees/<name>next todevsandboxes.toml;rmdeletes them with the container. worktree-linksymlinks one shared copy into each worktree;worktree-includeor a.worktreeincludecopies instead.- ’s config dir is mounted from the host: one login for every instance.
Agent instructions
Set up devsandbox so several sessions can work on my repo at <repo path> in parallel, each in its own sandbox instance on its own git worktree and branch.
- Read the devsandbox-cli and config-toml-spec skills first (load them if they are installed, otherwise read them from https://github.com/Nemikolh/devsandboxes/tree/main/skills). Follow them over your own assumptions: unknown config keys are hard errors.
- Find my devsandbox config dir: the folder holding devsandboxes.toml, passed to devsandbox as
-C <config dir>. If you cannot tell which one, ask me. - In devsandboxes.toml, add a
[sandbox.<sandbox name>]whosefolderpoints at <repo path> (relative to the config dir), with animagethat has the toolchain the repo needs. Install inpostCreateCommandand mount its host config dir (its login) into the container. - Put gitignored files every instance needs, like .env, in
worktree-link. - Validate with
devsandbox -C <config dir> lsand fix every error it reports before going on. - Start one instance per task with
devsandbox -C <config dir> run <sandbox name> --name <task>for each of <task names>. - Check
devsandbox -C <config dir> exec <task> git statusin each instance shows its own branch, anddevsandbox -C <config dir> exec <task> --versionworks. - Ask me before anything destructive: devsandbox rm, gc, rebuild --force, service rebuild, deleting files or branches.
Source: site/src/content/examples/parallel-agents.mdxEdit this page on GitHub(opens in a new tab)