Changelog.

0.8.0

Machines: sandboxes on your other hosts, over ssh, in the same CLI and dashboard, with your ssh-agent relayed only where you allow it. No more half-built sandboxes: an instance is recorded from the moment run starts, a failure leaves it listed as failed with its error, and Ctrl-C undoes the whole run. Every run, rebuild and start keeps a build log, and the dashboard runs them in the background instead of handing them the screen. run, rebuild, start, stop, rm and service rebuild now run in the host daemon, so a build outlives the terminal that started it, and -d leaves it running. The dashboard gets everything it shows from the daemon too.

Behaviour change: a failed run now leaves an instance to rm. Before, only a failing lifecycle command (postCreateCommand, …) kept its container, and a run that failed earlier (worktree, image build, container create) left its worktree, branch and services behind with no instance pointing at them. Now every failure keeps a failed instance; devsandbox rm <name> removes all of it, or devsandbox rebuild <name> retries.

devsandbox rebuild web-4   # retry a failed run
devsandbox rm web-4        # or remove everything it made

Added

• machine add installs devsandbox on the machine. When the machine has no devsandbox or another version, machine add offers to copy this one there (to ~/.local/bin/devsandbox, or over the old one); --auto-install skips the question and is needed off a TTY. A devsandbox in ~/.local/bin is found even when the machine’s login shell doesn’t put it on PATH. devsandbox --version prints the version.

devsandbox machine add me@my-server --auto-install

• Machines: sandboxes on other hosts, over ssh. devsandbox machine add <ssh target> registers a host running devsandbox (its config roots are offered to pick from, or pass --config '<path there>'); machine ls shows each one’s state, machine rm forgets it. Their sandboxes and instances then show in the dashboard next to yours, in a MACHINE column, and every key works on them, terminals included. On the CLI a name is looked up on every machine: one match is used wherever it is, my-server/test or @/test (this host) picks when it’s ambiguous. Verbs run on the machine with its login shell’s environment. Your ssh-agent reaches a machine only if you ask: machine add --agent, machine set <name> --agent on|off, or a on the dashboard’s Machines tab (5, listed while a machine is registered: each machine’s target, link state, agent and version) (off by default, takes effect at once), relayed by devsandbox rather than ssh -A. A login shell that prints a banner no longer makes the machine unreachable. exec, logs, inspect, done and rename run there over ssh. --machine <name> runs a command without a name there (ps, ls, stop --all, …). A machine that’s down keeps its last rows, marked unreachable. Not yet on machines: VS Code, the Inbox. Adding a machine means trusting it. Details: docs/machines.md.

devsandbox machine add me@my-server
devsandbox run api              # `api` is only defined on my-server
devsandbox exec test            # an instance there: over ssh
devsandbox stop my-server/test  # qualified, when `test` exists here too

• Port forwards into a machine’s sandboxes. devsandbox port my-server/web 3000 opens a port of an instance on a machine on this host, and port --machine my-server --service redis 6379 one of its global services. In the dashboard, p on a machine’s row does the same; the Ports tab lists those forwards with a MACHINE column, and like local ones they’re kept by the host daemon and come back after it restarts. Each forward is tunnelled over your own ssh to the machine, reconnecting if it drops. A machine’s forwardPorts stay on that machine: forwards into it are only the ones you ask for here. The machine needs this devsandbox version. Details: docs/architecture/daemon/forwards.md, Remote bridges.

devsandbox port my-server/web 3000
devsandbox port --machine my-server --service redis 6379

• Forwards show the listening process without lsof. The process listening on a forwarded port (node (pid 412)) now comes from the in-container helper, so it shows in images that have no lsof, and on a machine’s forwards too. Running instances pick up the new helper when restarted.

• API: forwards into machines. forwards.add takes machine (the forward still binds on this host; dir is the config root there), forwards.list takes machines: true to include them, and forward rows carry machine. Details: docs/reference/api.md, Forwards.

• API: machines. machines.probe|add|list|get|rm, roots.list, a machine param that runs a quick call or a verb on a machine, machines: true on instances.watch (rows tagged machine, plus each machine’s link state), instances.resolve and sandboxes.list (every machine’s matches), and found on instances.resolve’s answer. Details: docs/api.md, Machines.

• -d / --detach on run, rebuild and start. Returns as soon as the instance is registered and prints its name (run -d --json: the run record); the build goes on in the host daemon. Follow it with devsandbox logs --build <name> --follow, or watch its row in the dashboard.

devsandbox run -d web --branch fix/login

• API: the verbs as methods. run, rebuild, start, stop, rm and services.rebuild stream their output and phase over the API, plus instances.resolve, instances.cancel and sandboxes.list. Details: docs/api.md, Verbs.

• API: everything the dashboard shows. instances.list takes a depth (disk, listing or full, to skip the runtime or just its stats) and also answers thread_children. New: instances.procs and instances.signal (an instance’s processes and tracked runs; SIGTERM/SIGKILL one), instances.buildLog, instances.rename, instances.done, containers.logs and containers.inspect (devsandbox containers only), sandboxes.get and services.get (a config as written and resolved). instances.changed now also fires when an instance is created, removed, renamed, marked done or changes step. Details: docs/api.md.

• API: instances.watch. A client watching a config root gets its snapshot pushed as instances.snapshot every 2 s (cpu/mem every 7 s), from one poll shared by every watcher; the dashboard uses it, so two dashboards cost the runtime no more than one. stop, rm and services.rebuild take detach (a hang-up leaves them running), run, rebuild and start take tty (run on a pty of that size), and instances.buildLog takes ansi (keep the colours). Details: docs/api.md.

• status --json and ls --json sandbox rows gain dispatcher and worktree_branch: whether the sandbox is a dispatcher, and its resolved worktree-branch. Details: docs/json-output.md.

• Build logs. run, rebuild and start write their whole output, the containers’ build and lifecycle commands included, to a log per instance (~/.local/share/devsandbox/logs/<instance id>/build.log; the one before is kept as build.1.log, and rm deletes both). devsandbox logs --build <name> prints it; --follow keeps printing until the instance is done building. The command’s error, if it failed, is the last line. Builds run on a terminal of their own when you’re on one (or start them from the dashboard), so docker’s progress display and colours show as they used to, live and in the dashboard’s build log (b), which also scrolls with the mouse wheel. Piped, logs --build prints plain text.

devsandbox logs --build web-4 --follow

• ps, status --json and the dashboard show where an instance is. While it’s being made, an instance’s status is its step (preparing, building, creating, then the lifecycle command running, like postCreateCommand), and failed when it stopped partway; the dashboard’s Detail panel shows the failed step and error. status --json rows carry it as phase ({"state": "in-flight", "step": "building"} or {"state": "failed", "step": …, "error": …}), absent once the instance is ready; ps --json rows of instances with a container too. Details: docs/json-output.md.

Changed

• run, rebuild, start, stop, rm and service rebuild run in the host daemon. The command starts devsandbox serve if needed, hands it the work and prints its output as it comes, exiting as before. Closing the terminal, or losing the ssh session, no longer stops a build; Ctrl-C still cancels it (the rollback’s output shows, exit 130), and a second one stops it at once. Prompts (the sandbox picker, an ambiguous name, rm’s branch question) still happen in your terminal. If no daemon answers, one warning: line and the command runs in your terminal as before (on Windows it always does, with no daemon).

• The dashboard is a client of the host daemon. Everything it shows comes from devsandbox serve and every action goes to it, so it needs the daemon (it starts one when it opens, as before). If the daemon goes away, the last tree stays on screen marked stale with the reason, and actions say the daemon is needed. On Windows, which has no daemon, the dashboard isn’t available for now. It no longer runs an autostart pass of its own when it opens; the daemon’s covers every config root that has instances.

• The dashboard no longer takes over the screen for stop, rm or a service’s rebuild. They run in the daemon, and the status line says how they ended, or why not (e.g. rm refusing a dirty worktree). rm’s question about deleting the branch is a y/n popup; esc removes nothing. Quitting the dashboard while one of them is still going leaves it running.

• s on a stopped instance starts it like devsandbox start. It used to be a bare container start; it now also runs the services, postStartCommand and the autostart pass, in the background, with a build log under b.

• Each command runs with your shell’s environment. The daemon runs every request with the caller’s whole environment, never its own: ${localEnv:…} in the config, SSH_AUTH_SOCK, GIT_*, DEVSANDBOX_RUNTIME and PATH are those of the shell you typed the command in, even when the daemon was started long ago or by systemd.

• The dashboard runs run, rebuild and start in the background, through the host daemon. It no longer steps aside for the build and waits for a key: the command keeps going even if you quit the dashboard, a status line says when it started, and the instance’s row shows its step as it goes, failed included. When it can’t reach the daemon, the status line says one is needed instead. b on an instance opens its build log, following it while it builds. d on a row still building asks to cancel it; on a failed row it removes the instance, and s rebuilds it.

• The host daemon follows container events. Instead of listing containers every few seconds, it wakes on the runtime’s events and on edits to your config, so the dashboard reflects a change sooner and an idle daemon (kept up by serve install) costs next to nothing.

• Ctrl-C rolls a run back. Cancelling a run (Ctrl-C or SIGTERM) removes everything it had made: container, services and network, volumes, worktrees, the branch it created if it has no new commits, and the instance itself. A second Ctrl-C quits at once without cleaning up. A cancelled rebuild leaves the instance failed.

• Commands leave an instance alone while it’s being made. start, stop, rename, rebuild and rm (even with --force) refuse an instance whose run or rebuild is still going and say what it’s doing; start also refuses a failed one and points at rebuild and rm. rebuild --all and autostart skip both. exec works once the container exists, so you can shell into one whose postCreateCommand failed. A dispatcher’s devsbd ensure of such a child fails with a message naming its step instead of starting or recreating it.

Fixed

• Copying in the dashboard works in terminals that ignore OSC 52, such as iTerm2 by default. That covers the dashboard’s own selections and copies from apps in its terminal tabs, including tabs on a machine. A dashboard running on your machine now also puts the text on the clipboard itself (pbcopy, wl-copy or xclip).

• Upgrading devsandbox under a running dashboard or daemon no longer breaks it. Once the binary was replaced, new terminal tabs, builds and other spawned commands failed until a restart; they now run the new one.

• A run killed outright shows as failed. A run or rebuild killed by SIGKILL, the OOM killer or a reboot used to leave its instance looking half-made or not at all; it now shows as failed with interrupted, ready to rebuild or rm.

• Two runs started at once no longer share an instance name. Both could pick the same default name and build over each other; now the second stops with an error before making anything.

0.7.1

Critical fix: upgrade if you run more than one instance of the same repo. A git worktree prune or git gc inside one sandbox could delete git’s records of every other instance’s worktree, leaving them with fatal: not a git repository. devsandbox now locks the worktrees it creates. After upgrading, run devsandbox start once on each existing instance to lock its worktree (safe on a running one), and devsandbox rebuild it to also get the git gc guard. This release also adds local-folder features and fixes a few host-daemon start and shutdown issues.

devsandbox start <instance>

Added

• Local-folder features. A features key starting with ./, ../ or / is a feature folder (devcontainer-feature.json + install.sh) resolved against the config dir, so a config can ship its own feature without publishing it to a registry. Options, containerEnv, installsAfter, mounts, privileged and entrypoint work as for OCI features. Editing a file in the folder marks the sandbox’s instances as drifted, so devsandbox rebuild picks the change up, and devsandbox ls warns when the folder or its devcontainer-feature.json is missing.

[template.base.features."./features/toolkit"]
ripgrep = true

Fixed

• Critical: git worktree prune inside a sandbox no longer breaks the other instances’ worktrees. A container sees the repo’s worktree records but not the other checkouts, so a prune (or git gc) there deleted their records and left each one with fatal: not a git repository. devsandbox now locks the worktrees it creates, so prune and gc skip them; existing instances get locked on their next start. An instance whose record was already pruned gets a warning on start instead; git won’t work in it until the record is restored. Containers also get gc.worktreePruneExpire=never (after a rebuild for existing ones), so git gc leaves worktrees you made yourself alone too. Details: docs/worktree-locking.md.
• devsandbox rebuild starts the host daemon, like run and start. A rebuilt dispatcher or inbox = true instance with no dashboard open and no daemon running had no host, so its devsbd control commands exited 75 until some other command started one.
• An upgrade or devsandbox serve shutdown no longer brings back the old daemon. A dispatcher’s child op still running while the daemon shut down could start a fresh daemon from the old binary, which then kept running instead of the new one (or undid the shutdown).
• The “no host connected” error says how to get one. Control commands that exit 75 now suggest running any devsandbox command (or devsandbox serve install) instead of opening the dashboard, which no longer serves them.

0.7.0

A per-user host daemon now keeps notifications, dispatchers and port forwards working with the dashboard closed, and serves an API that editors, GUIs and the new npm connect() client can drive. Sandboxes can keep one Inbox thread per item: a header with a state and buttons, and a conversation of messages, forms and your replies, answered from the dashboard, the new devsandbox inbox command or any API client, with events streamed back as they happen. The Inbox becomes a list of what’s waiting on you rather than a log, and instances can be marked done instead of removed. VS Code can open straight at a file and line.

Added

• A host daemon keeps devsandbox live with the dashboard closed. devsandbox serve is a per-user background process that now owns the connection to every running sandbox’s helper: the ssh-agent relay, notifications and desktop popups, dispatcher control commands and port forwards. You don’t start it: the dashboard, run, start and the commands that relay your ssh-agent start it when needed, and it exits 10 minutes after its last user left (a dashboard, a forward, a running dispatcher or inbox = true sandbox). A newer devsandbox takes over from an older daemon by itself. devsandbox serve install runs it from login as a systemd user unit (Linux) or a LaunchAgent (macOS), for sandboxes the container runtime restarts on boot; an upgrade repoints the installed unit at the new binary, and serve uninstall removes it. To keep it from idling without a unit, use devsandbox serve --keep-alive or ~/.local/share/devsandbox/daemon.config.toml. exec, start and run no longer start an ssh-agent bridge of their own: one bridge per container, relaying the agent of whichever session last ran a command. Details: docs/serve.md.

# ~/.local/share/devsandbox/daemon.config.toml
[serve]
keep-alive = true

devsandbox serve install

• Port forwards outlive the dashboard. Ports-tab forwards and every sandbox’s forwardPorts now run in the host daemon, so closing the dashboard no longer drops them, and every open dashboard shows the same ones. Forwards you add are saved in ~/.local/share/devsandbox/forwards.toml and come back on the same host port after a daemon restart or a reboot, until d stops them. devsandbox port still forwards in the foreground until you stop it.

• Inbox threads. A sandbox that declares inbox = true can keep one thread per item in the Inbox (a PR, an email to answer). devsbd thread put sets its header: a title, a link, a state (needs-you, active or done), a status, the child instance it’s about, up to 9 buttons and an optional reply box (compose, with a hint line under it saying what sending does). A put that changes nothing is ignored (no unread mark, no popup), so a sandbox can simply re-send all its threads on every pass; a desktop popup only fires when a thread enters needs-you, and state and status changes show as one-line markers in the thread. devsbd thread send adds a message under the header: markdown and key/value fields blocks, identified by an id of your choosing, so re-sending the same message is free and sending changed content edits it in place; devsbd thread withdraw takes one back. Everything is queued like notify, so it works with no daemon running. devsbd thread rm drops a thread, devsbd thread ls [--feed] lists yours back, messages included. dispatcher alone only grants the child commands, so a dispatcher that wants threads declares both. A rejected put or send shows up as an error notification from your instance, with the reason. Full reference: docs/automations-guide.md.

[sandbox.pr-dispatcher]
dispatcher = { spawn = ["web"] }
inbox = true

devsbd thread put --json '{"key":"pr-123","title":"#123 fix login","state":"needs-you","status":"review replies","child":"pr-123","actions":[{"id":"retry","label":"Retry"},{"id":"done","label":"Done","done":true}],"compose":{"hint":"Starts a run with your message"}}'
devsbd thread send --json '{"thread":"pr-123","id":"run-1","blocks":[{"type":"markdown","text":"Addressed 3 of 4 comments, **1 needs your call**."}]}'

• Forms in messages. A message can carry a form: choice, text and yes/no questions, with defaults (a text default is how you offer a draft for editing). The dashboard pins open forms under the thread’s header: tab between questions, space to pick, e to edit a text answer, enter to see what will be sent and enter again to submit. Half-filled answers are saved as you go, so they survive a restart and show the same in every dashboard. Submitting sends one submit event with every answer, defaults filled in, and the thread shows what you answered (you answered "<title>" over each label: value) where you’ll read the owner’s reply to it. A question can follow up another (under), shown indented under it, and only be asked while one of its options is picked (when): a reply text that only matters for “Post the reply” is hidden, not required and sent as null when you pick “Don’t reply”.

• devsandbox inbox answers threads from a shell. ls and show (with --json) read the Inbox without the daemon; reply, act, submit, done and reopen answer a thread, named <owner>/<key> or by the id ls shows. The owner gets the same events as from the dashboard.

devsandbox inbox ls --view needs-you
devsandbox inbox reply pr-dispatcher/pr-123 "Rebase it first"

• An API for editors and GUIs. The host daemon serves a JSON-lines API on a unix socket: the Inbox (threads, replies, actions, forms, done/reopen, notifications), instances, port forwards, and change notifications. devsandbox api --stdio relays it over stdin/stdout for clients that can only spawn a process; it exits 0 when its input ends and 75 only when the daemon hung up first. The npm package’s connect() wraps it with typed inbox, instances and forwards methods and events. Whoever can open the socket can act as you on every sandbox, like docker.sock. Reference: docs/api.md.

const api = await devsandbox.connect({ name: 'my-tool' });
await api.subscribe(['inbox']);
const [t] = await api.inbox.list('needs-you');

• Thread buttons that act right away. A button can carry a built-in host action that runs in the dashboard with no round trip: open VS Code on the thread’s child (at a file and line), a terminal, its logs, a port forward, a link, or rm with the usual confirm. On a stopped child, VS Code, the terminal and the forward start it first (the button says (stopped)); logs don’t, since a stopped container’s log says why it stopped. The target is always the thread’s child or the thread’s owner itself, never another instance, and there is no arbitrary host command.

• Events: your answers, back to the thread’s owner. Every other button, a reply, a form submission, marking a thread done and reopening it become events the owner reads with devsbd events (JSON lines, each naming its thread). --wait SECS returns as soon as there’s one; --follow keeps a stream open and prints each event the moment it happens, with a ping after 30 s of quiet, and a newer follower from the same instance replaces the older one, so two copies of a loop never both act on a click. --thread KEY narrows either to one thread. Delivery is at least once: events stay until the owner acks them with devsbd events ack <id>… after saving its own state. devsbd features lists the newer verbs a helper has (thread-send, events-follow, …), so a script can check before using them.

devsbd events --follow
devsbd events ack e-1790900001-3f2a

• Done instances. An instance marked done keeps its container, worktree and runs, and shows dimmed with a ✓ in the dashboard and (done) in ps, until you remove it. Mark it with devsandbox done <instance>, a thread’s Done, or a dispatcher’s devsbd done <key>; clear it with devsandbox undone, u on the thread, or a dispatcher’s ensure reusing it. devsbd ls, ps --json and status --json report done. npm: done(name) / undone(name), and done on instance rows.
• d removes the selected instance in the dashboard. Like s, it acts right away with no prompt: it runs rm, which still refuses a dirty worktree and asks before deleting the branch.

devsandbox done web-pr-123

• devsandbox vscode --goto opens VS Code at a file and line. The path is relative to the instance’s workspace folder. It opens (or focuses) the window as before, then has the in-container helper open the file in that window, waiting up to 30 s for it to attach; if that fails, the window still opens and the output says why the line was dropped. In the dashboard: :code <instance> --goto path:line.

devsandbox vscode web-2 --goto src/main.rs:42:7

• Select and copy text with the mouse in the dashboard. Drag in any pane to select text inside it, without borders or the panes next to it. Releasing copies it to your clipboard (copy on select, on by default); with that setting off, ctrl-shift-c or cmd-c copies it, and so does ctrl-c over a selection, for terminals that send that key plain or keep ctrl-shift-c for their own copy (Alacritty, GNOME Terminal, kitty and most Linux terminals: there the dashboard tells you ctrl-c). The copy goes through your terminal (OSC 52), so it works over SSH and from a container; under tmux, enable allow-passthrough. Inbox threads copy as rendered, with bullets, quotes, tables and links as shown and wrapped lines joined back, and dragging past the edge scrolls so a long message copies whole; the config, help and logs views work the same way. shift-drag still gives your terminal’s own selection. In the integrated terminal, apps that use the mouse (vim, tmux, zidane) now get your clicks, drags and hover, and what they copy to the clipboard now reaches yours (a setting turns that off); in a plain shell you select the output, scrollback included.

• Dashboard settings. ? is now Settings & help: the settings on top, toggled with space, enter or a click (tab moves between them), and the key reference below. They are saved per user in ~/.local/share/devsandbox/dashboard.toml. copy on select (on) copies a mouse selection on release; terminal clipboard (on) lets apps in the integrated terminal set your clipboard.

Changed

• The Inbox shows what’s waiting on you. Side by side: a card list on the left (title, compact age, state/level chip and sender; a selected card gets an accent bar), the selected thread always open on the right, with a ‹ Needs you │ Active │ Done │ All › strip above the list stepped by ←/→. The tab count and the yellow ✉N on instance rows now count threads that need you and unread notifications, not every unread record. In the thread, the header stays pinned at the top (title, the same state and status chip as the card, the child and whether it’s stopped, the buttons), open forms sit under it, and the conversation runs newest first, so the newest thing is read first. enter moves focus into the thread pane: 1–9 run buttons, r replies in a box at the bottom of the pane (shown only when the thread takes replies; it wraps, grows to six rows, and the line under it says what sending does; alt-enter adds a line), tab moves to an open form, d marks done, u reopens, o/t/l/p act on the thread’s child, and enter opens the link; esc steps back. The per-instance grouping and inline folding are gone: a notification’s earlier records are listed in the pane. A thread is read when selected and again if it changes while selected; notifications are marked read the same way or when you leave the Inbox after seeing them. d on a notification dismisses it and on a thread marks it done; D clears notifications only.

• The dashboard takes more mouse clicks. Click a tab title to switch tabs. In the Inbox, click a card to select it, a view name to switch views, the thread or its reply box to focus them; the wheel moves through the cards or scrolls the thread.

• Inbox text is rendered as markdown. Thread messages, replies and notification bodies show headings, lists, code blocks, quotes, links and tables (aligned when they fit) instead of raw ** and backticks; titles and statuses get inline code and emphasis. Long lines wrap at word boundaries. Press m on a thread to see the source. Control characters from containers are stripped before they are stored or drawn.

• A newer devsandbox updates the helper in running instances. Before, a running dispatcher only got new devsbd verbs after devsandbox start; now the host daemon of a newer devsandbox installs them, so opening its dashboard (or any command that starts the daemon) is enough.

• The Inbox is stored in inbox.json. It’s shared by every dashboard, the host daemon and devsandbox inbox. On first use, the notifications of the old inbox.toml are carried over; threads from earlier builds aren’t (their owners re-send them on their next pass).

• devsbd ensure, stop, rm and done answer JSON. Each prints one JSON line instead of the bare instance name, so a dispatcher never parses prose: ensure gives name, key, sandbox, state, and whether the child was created or started; stop gives state: "stopped", rm removed: true, done done: true. A script that read the name from stdout reads .name now. Errors are unchanged: a message on stderr and a non-zero exit.

• rm cleans up merged branches without asking. With no flag, rm first runs git fetch --prune origin, then decides about the branch the worktree has checked out. If every commit on it is already on its remote branch, or the remote branch it tracked has been deleted (a merged PR), the branch is deleted without a prompt. Only a branch with commits that exist nowhere else still prompts, and off a TTY it is kept. Branches you reused with --branch follow the same rules now. The default branch (origin/HEAD, main, master) is never deleted. When rm deletes a branch, it also deletes the branch run created if that branch is an ancestor of it. --delete-branch / --keep-branch still decide outright.

Fixed

• Instances no longer vanish from state while their container stays. Commands saved the whole state as they had loaded it, so a slow run, rebuild or rm running alongside another command could drop the instance that command had just recorded, leaving its container and worktree behind with no entry. A dispatcher child lost this way blocked its key for good: every devsbd ensure failed with container … already exists but is not in state. State changes are now applied under a lock to the current file, written atomically. A dispatcher’s ensure also replaces such a leftover container when it carries that dispatcher’s label and its worktree is gone; if the worktree is still on disk, ensure refuses and names the worktree, so you can check it for work before removing it on the host.

• SSH works in a dispatcher’s child as soon as devsbd ensure returns. A child that ensure had just started had no working ssh-agent for about a second, so a devsbd exec right after it (git fetch, git push) failed with Permission denied (publickey). ensure now waits (up to 12 s) for the agent relay of a child it created or started; if it isn’t ready by then, its answer carries a note saying why.

• Long commands in the : prompt stay visible. Text past the prompt’s width was hidden though it was still run; the prompt now scrolls sideways to keep the cursor in view.

• A press in the Inbox thread pane no longer grabs the divider. A press on the pane’s first text column started resizing the list/thread split; now only the borders do.

• The help and logs screens keep the mouse to themselves. With either open, clicks and the wheel reached the integrated terminal hidden underneath.

• Apps in the integrated terminal get the mouse and the clipboard. They never received clicks or drags, and what they copied to the clipboard was dropped.

• Dismissed notifications no longer come back with several dashboards open. Each dashboard kept its own copy of the Inbox and saved it over the others’, so records dismissed in one reappeared from another, and restarts seemed to add clutter. All dashboards now share one store, so a dismissal in one is gone from all.

• A notification is no longer lost if the dashboard dies while receiving it. The container’s copy was dropped as soon as the dashboard said it had it, before it was saved; now it’s saved first, and resent otherwise.

• rm asks about the right branch. It used to name the branch run created, even after the worktree had switched to or renamed another branch. Now it reads the worktree’s current branch before removing it. For instances from before branches were recorded that have since been renamed, the old fallback guessed the branch name from the new name; it now uses the instance’s original name.

0.6.0

The config file is now devsandboxes.toml, and it can be written in YAML too; an existing config.toml is renamed for you. Extra folders get their own worktree when someone else owns the checkout, rm --force clears out stuck instances, dispatchers can see which branches are in use, and the dashboard opens instantly and keeps its Inbox across restarts while putting far less load on dockerd.

Added

• YAML configs. devsandboxes.yaml (or .yml) works in place of devsandboxes.toml: same keys, extends merging and validation, only the syntax differs. A sandbox hashes the same in either format, so converting a config doesn’t mark instances for rebuild. Keep one config file per config dir; with more than one, devsandbox stops with an error.

sandbox:
  web:
    folder: ../web
    image: mcr.microsoft.com/devcontainers/base:ubuntu
    services: [database]

• devsbd branches <sandbox> tells a dispatcher which branches are already checked out. It prints a JSON list of every branch in a worktree of the sandbox’s repo and who holds it: one of the dispatcher’s own children, another instance, the base checkout, or a worktree devsandbox doesn’t know. It reads git on the host each time, so a git switch inside an instance is seen. With --ahead, each row also gets the number of commits origin doesn’t have yet, and local branches that are ahead but not checked out are listed too. A dispatcher can use it to leave alone PRs that someone is working on locally. The sandbox must be in the dispatcher’s spawn. Running dispatchers pick up the new helper when restarted.

devsbd branches web --ahead

• rm --force (-f) removes an instance whatever state it’s in. A worktree with uncommitted or untracked changes is removed anyway, changes discarded, instead of rm refusing. A step that fails (a worktree git won’t remove, a repo the host refuses to run git in) prints a warning and rm carries on, so the instance still leaves the list. Whatever couldn’t be removed stays on disk. The branch of a worktree that was left in place is kept. In the dashboard: :rm --force <instance>. npm: rm(name, { force: true }).

devsandbox rm --force web-2

• The dashboard’s Instances tree has a TYPE column when a sandbox is a dispatcher. Instances of a dispatcher sandbox read dispatcher, the others -. Without any dispatcher in the config the column isn’t shown.

Changed

• The config file is now devsandboxes.toml. An existing config.toml is renamed the next time devsandbox runs in its config dir (with a notice on stderr), and is read as-is until then. A config.toml with no sandbox, template or services table isn’t a devsandbox config and is left alone.

• Inbox times say how long ago a notification came in. The TIME column reads just now, 12s ago, 5 min ago, 3h ago, 1 day ago, … 6 days ago, then the date and time (Oct 2 14:32) once a notification is a week old. Before, it showed only the time of day, so yesterday’s notifications looked like today’s. The Detail pane shows the date and time.

• folders entries get their own git worktree when the checkout belongs to someone else. If an extra folder is a git repo and it’s another sandbox’s folder, or another instance already mounts it, the instance now gets a worktree of it, detached at that checkout’s HEAD. Before, the instance mounted the live checkout, so the owner switching branches changed what the instance saw. The worktree is kept across rebuild and removed by rm. Dispatcher children always get one. To keep the old live view for an entry, write it as a table with worktree = "never", or use "always" to force a worktree:

[sandbox.web]
folder = "../web"
folders = { "/workspaces/api" = "../api", "/workspaces/.shared" = { path = "../.shared", worktree = "never" } }

• A sandbox’s own folder now also gets a worktree when another instance mounts that folder directly as a folders entry.

• The Inbox keeps its history. Notifications are saved in inbox.toml next to state.toml, so they survive closing the dashboard; d/D remove them from the file too. A notification with the same --key no longer replaces the earlier one: it becomes the head of a thread, with the older ones folded under it (→ to show them). With more than one instance sending, the Inbox groups them per instance, foldable like the Instances tree. The limit is now 200 notifications per instance (was 50, and 200 overall).

• worktree-link no longer migrates old shared-files/<sandbox>/ stores. The automatic move only relinked the instance being run, so every other instance on the same repo was left with dangling links. A link into an old store is now skipped with a warning that shows where the file should go. Move it there, delete the old link, and rebuild.

• The dashboard opens instantly and fills in as the runtime answers. The tree is drawn from state.toml and the config right away, statuses (… until then) arrive with the first container listing, and CPU/MEM after that. Before, the dashboard waited about 1.5s for docker stats and showed “no sandboxes defined” meanwhile.

• The dashboard puts much less load on dockerd. CPU/MEM now refresh every 7s instead of every 2s (statuses still every 2s), the runtime version is asked once, and process lists are only fetched while the Instances tab is open. Instance drift is read from the container listing instead of two docker inspects per instance.

Fixed

• Listing containers no longer makes dockerd compute their disk sizes. Every ls, ps, gc, autostart pass and dashboard refresh asked for container sizes as a side effect of the output format, which spiked dockerd’s CPU every 2s while the dashboard was open and made each listing take ~300ms instead of ~20ms.

• Opening VS Code no longer clears an instance’s extensions. devsandbox vscode and the dashboard’s o read the sandbox config from the current directory, not from the instance’s own config directory. Run from anywhere else, the extensions list was rewritten as empty, so VS Code didn’t install anything. They now read the instance’s own config. If that config still can’t be read, the list is left as it was. Instances already hit by this get their list back the next time you open VS Code from the new version.

• An rm that failed partway can be retried. A worktree an earlier rm had already removed made the next rm fail too; it is now pruned instead.

• The dashboard no longer warns about mount sources run creates itself. shared-volumes paths and per-instance mount sources that don’t exist yet are made by run, so a sandbox with no instance no longer shows them as problems.

• VS Code labels the primary workspace root by its folder name, matching the extra folders roots, instead of the instance name.

0.5.0

Sandboxes can now start themselves after a reboot and run unattended dispatcher scripts that create, drive and clean up their own child instances. Messages from inside containers show up in the dashboard and as desktop notifications. See docs/automations-guide.md. run --json, a command-less exec and exact-name matching make devsandbox easier to drive from scripts and other programs, and the docs now live at devsandboxes.com.

Added

• autostart: a sandbox’s instances come up once per boot, when the dashboard opens or after your first devsandbox run / start. A sandbox with no instance yet gets one; dispatcher children are left to their dispatcher.
• autostart = "runtime": docker and podman restart the containers themselves at boot (--restart unless-stopped), with no devsandbox process needed. Podman also needs podman-restart.service enabled. On Apple container it behaves like true. Changing autostart never marks an instance as drifted; the next start applies it in place.

[sandbox.triage]
folder = "../triage"
autostart = "runtime"   # or true

• Boot hook: new containers run devsbd boot on every start, which brings back the helper daemon and, in runtime mode, postStartCommand (output in /run/devsandbox/boot.log). Containers created before this need devsandbox rebuild --force to get it.
• devsbd notify: any sandbox can send the user a message. It is queued inside the container until a dashboard is open, then shown in the new Inbox tab (unread badges on instance rows, enter opens an http(s) link, d/D dismiss) and as a desktop notification (notify-send / osascript).

devsbd notify --level warn --key pr-123 --link https://github.com/o/r/pull/123 "PR 123 needs you"

• Dispatchers: a sandbox that declares dispatcher can manage child instances through devsbd, while the dashboard is open. Children are named <sandbox>-<key>, always get their own worktree, are marked ⇠ <dispatcher> in the TUI, and outlive the dispatcher. Host-side operations log to <data>/devsandbox/logs/dispatch-*.log. Exit codes: 75 when no dashboard is connected, 77 when denied.
  • spawn = ["*"] means every sandbox in the config root except other dispatchers, and it grants their mounts, docker socket and privileges. Children can never be dispatchers themselves.
  • max-instances defaults to 10 and counts stopped children too.
  • --branch accepts plain branch names only ([A-Za-z0-9._/-]) and is used literally, with no ${…} expansion.
  • --env refuses names that could take over processes in the child: PATH, HOME, SHELL, LD_*, DYLD_*, GIT_*, NODE_OPTIONS, PYTHON* and similar. Its values are kept across a devsandbox rebuild of the child, including when ensure recreates a missing container. On an existing child, ensure --env replaces the saved values, and every command devsandbox runs in the child (exec, dashboard terminals, devsbd exec runs, lifecycle commands) uses them from then on, over a same-named remoteEnv; already-running processes keep the old ones until a rebuild.

[sandbox.pr-dispatcher]
folder = "../pr-dispatcher"
autostart = "runtime"
dispatcher = { spawn = ["web"], max-instances = 10 }   # "*" = any non-dispatcher sandbox
postStartCommand = "nohup ./loop.sh >loop.log 2>&1 &"

devsbd ensure web --key pr-123 --branch feat/x   # create or start web-pr-123
devsbd exec pr-123 --detach -- zidane -p "babysit PR 123"
devsbd run logs pr-123 <id> --follow
devsbd ls; devsbd stop pr-123; devsbd rm pr-123

• Runs: commands started with devsbd exec are tracked in the child (id, log, exit status). Follow them with devsbd run ls|logs|wait, clean them up with devsbd run rm (--force kills a running one) and devsbd run prune --keep N; the TUI shows a child’s last runs under its processes.
• devsbd is on PATH in containers (/usr/local/bin/devsbd).
• forwardPorts: while the dashboard is open it forwards each running instance’s configured ports to 127.0.0.1, the same way devsandbox port does (no container restart). Each instance keeps its host ports across dashboard restarts, and a port already taken moves to the next free one up. A global service’s port is forwarded once, however many instances list it. In the Ports tab these rows are marked (config); d stops one until the dashboard reopens.

[sandbox.api]
services = ["db"]
# 3000, "db:5432" as in devcontainer.json; "8080:3000" / "15432:db:5432" pick the host port
forwardPorts = [3000, "8080:3000", "db:5432"]

• run --json: prints one {"schema": 1, "data": {...}} document for the new instance (name, instance_id, sandbox, container, workspace, folder, base_folder, worktree, branch; the last two null without a worktree). Everything child processes print (image builds, docker run, git, lifecycle hooks, autostart) goes to stderr, so stdout parses as-is for programmatic and GUI callers.
• exec <name> without a command opens a login shell (zsh, else bash, else sh), the same one the dashboard’s terminal opens. With neither -i nor -t given it runs with -i, plus -t when stdin is a TTY, so it works as is from a terminal or a pty (node-pty); explicit flags are used as given.
• npm: execArgv(name, cmd?, { tty, interactive }) returns { file, args } for spawning devsandbox exec yourself (node-pty, child_process.spawn) without shell quoting.
• rm --delete-branch / rm --keep-branch answer the “delete branch?” question without prompting, so scripts and other callers without a TTY can clean up the branch run created. --delete-branch deletes it like answering yes (git branch -D, so unmerged commits go too); --keep-branch keeps it. Branches run reused rather than created are always kept. With neither flag, rm still asks on a TTY and keeps the branch otherwise. npm: rm(name, { deleteBranch }), where true / false pass --delete-branch / --keep-branch.
• Docs site at devsandboxes.com: a quick start, a playable tour of the dashboard, the full config.toml reference, the Node API reference, ten worked examples (parallel coding agents, shared and per-instance services, package caches, ssh-agent and git push, babysitting pull requests, porting a devcontainer.json, …), full-text search (⌘K / Ctrl+K) and this changelog.

Changed

• Worktrees reuse existing branches. run --branch X, and a dispatcher’s devsbd ensure --branch X, no longer fail when X exists:

  • a local X is checked out as it is;
  • an X that only exists on origin (a PR head, for example) becomes a local branch tracking origin/X, so a plain git push updates it;
  • a branch that’s already checked out somewhere else gives an error saying where.

  rm only offers to delete branches devsandbox created itself.

• New containers use sh -c '… devsbd boot & exec sleep infinity' as their command instead of sleep infinity, so images need /bin/sh.

• start sets the container’s restart policy from autostart, overwriting a policy set by hand.

• While the dashboard is open it keeps a helper connection to every running instance that has the helper, not only when an ssh-agent is being relayed.

• devsandbox status --json instance rows include instance_id and, for children, dispatcher.

• rebuild applies worktree-include. Before, adding a pattern marked instances as drifted, but the rebuild copied nothing. Now rebuild copies any missing matching files into the worktree; existing files are never overwritten. A copied file you delete on purpose comes back on the next rebuild, so drop the pattern instead.

• devsandbox port 3000 (and the Ports tab) moves to 3001, 3002, … when 3000 is taken on the host, instead of a random port.

• A service ports entry that gives only the container port ("5432") now gets the same port on the host when it’s free, instead of a random one. If the port is taken, the runtime still picks one.

• An exact instance name wins. With instances web and web-2, devsandbox exec web (and rm, stop, logs, …) now means the instance web instead of an ambiguity that failed off a TTY and prompted on one, including inside a pty. An exact instance id counts too; sandbox and folder names only apply when nothing matches exactly. exec now uses the same resolution as the other verbs, so it also accepts an instance’s id after a rename.

• npm (breaking): run() resolves with the new instance’s record (RunRecord) instead of its name; use (await run(...)).name for the old value. It calls run --json, so build and autostart output can no longer end up as the “name”.

• In the generated VS Code workspace, the main folder is labelled with its directory name (webcontainer) instead of the instance name (webcontainer-sqlite), like the extra folders roots. If an extra root has the same directory name, the instance name is kept. Existing instances pick this up on rebuild --force.

Fixed

• rm on a dirty worktree no longer leaves an instance without its container. rm removed the container, volumes and services first, then git worktree remove refused the uncommitted or untracked changes, stranding the instance. It now checks the worktree first and refuses with the list of changes, removing nothing.
• Keyboard chords like ctrl+m reach apps in dashboard terminals. In terminals that support the kitty keyboard protocol (kitty, Alacritty ≥ 0.13, Ghostty, WezTerm, foot, iTerm2 ≥ 3.5), the dashboard now turns the protocol on and passes it through to apps inside its terminals that ask for it. zidane’s ctrl+m, for example, no longer arrives as Enter. Shells and other apps that don’t ask for it get the same keys as before. GNOME Terminal and tmux don’t support the protocol, so there ctrl+m and Enter still can’t be told apart.
• The mouse wheel scrolls full-screen apps in dashboard terminals. It used to scroll only the terminal’s own scrollback, which full-screen apps don’t have. Now apps that track the mouse (zidane, vim with mouse=a, htop) get the wheel directly, and pagers like less and man get ↑/↓. Shells still scroll their history.
• Forwarded ports reach servers listening only on IPv6 loopback. Dev servers told localhost (webpack-dev-server, Vite, Node 17+) often bind only [::1], while forwards dialed 127.0.0.1, so every connection was refused. A loopback dial now also tries the other family (127.0.0.1 ↔ ::1). Running instances pick up the new helper when restarted.
• worktree-link works for several sandboxes on the same folder. The shared copy used to live in one store per sandbox. The base checkout can only link to one of them, so the second sandbox’s worktrees got nothing. The store is now per repo: shared-files/<folder name>-<hash>/, shared by every sandbox on that folder. The next run or rebuild moves files from the old shared-files/<sandbox>/ stores and relinks the base checkout and worktrees. Instances still running on an old store need a rebuild. If two old stores held different copies of a file, the one the base checkout linked to wins, and the other stays where it was with a warning.
• ssh-agent forwarding no longer breaks run on macOS + docker in builds without the helper (cargo install). The fallback bind-mounted the Mac’s launchd agent socket, which can’t cross into the runtime VM, so docker run failed with mkdir …/agent/<instance>.sock: file exists. It now mounts Docker Desktop / OrbStack’s /run/host-services/ssh-auth.sock instead. Builds that embed the helper were never affected.
• devsandbox port and the Ports tab work on macOS. Accepted connections inherited non-blocking mode from the listener there, so every relay read failed with os error 35 and no forwarded connection got through.
• 0.4.0 never reached crates.io (the publish step failed on the release archives in the checkout); cargo install devsandbox goes straight from 0.3.4 to this release.

Security

• Git on the host can no longer run code planted by a sandbox. Worktree instances mount the base repo’s .git read-write, so a container could plant hooks or command-running config (core.fsmonitor, core.sshCommand, filter drivers, include.path, …) that the host’s git worktree add / fetch / worktree remove would then run as you.
  • Every git command devsandbox runs on the host now has hooks and fsmonitor turned off.
  • It first checks the repo’s local config against an allowlist. If a key could run a command, it refuses and names the key: review it and remove it. ext:: remotes and object alternates are refused as well.
  • This affects every worktree instance, not only dispatcher children.
• The commands devsandbox runs as root inside containers (helper install, boot file, Apple /etc/hosts update, workspace file) use /bin/sh with a fixed PATH, so they don’t depend on the container’s PATH.
• Limits on what a container can make the host do:
  • at most 8 concurrent notify/control handlers per container;
  • output from host-run commands is capped and timed out (5 min for in-child commands, 30 min for dispatch operations, which are killed with their whole process group);
  • desktop popups are rate-limited per instance (3 at once, then one every 10 s), and repeats of the same key within 60 s don’t pop up again;
  • the inbox keeps at most 50 entries per instance (200 overall);
  • devsbd run ls lists only the newest 50 runs and shortens long command lines.

0.4.0

Worktree instances can now bring along the gitignored files a repo needs to run, like .env files, instead of starting without them.

Added

• Copy gitignored files into new worktrees. A repo’s .worktreeinclude file is always honored, and worktree-include adds more patterns (gitignore syntax). Matching untracked files are copied from the base checkout into each new worktree and never overwrite existing files.
• Share gitignored files across all instances. Each worktree-link path is moved to one shared copy under shared-files/<sandbox>/, and every worktree gets a symlink to it. An edit in one instance shows up in all of them. This also works on Apple container, which can’t bind single files. Globs work within one path segment (* / ?), and a leading ./ is accepted.

[sandbox.web]
folder = "../web"
worktree-include = ["fixtures/*.local.json"]   # copied once, per worktree
worktree-link = [".env", "packages/*/.env"]    # one live copy shared by every instance

• A CHANGELOG.md, which is also used as the GitHub release notes.

Fixed

• TUI: pressing s to start an instance refreshes the list shortly afterwards, so the new state appears right away.

0.3.4

On-demand port forwarding, devcontainer features that need privileges or entrypoints (docker-in-docker works now), and a full config.toml reference.

Added

• devsandbox port: makes a port inside an instance or one of its services reachable on the host, without publishing it when the container is created and without a restart. Forwards reconnect by themselves after the target restarts or is rebuilt. When the image has lsof, the command shows which process is listening. Unix hosts only.

devsandbox port api 3000                      # localhost:3000 -> api's :3000
devsandbox port api 8080:3000                 # bind host :8080 instead
devsandbox port api --service postgres 5432   # api's postgres, via the api container
devsandbox port --service redis 6379          # a global service, no instance named

• TUI Ports tab: lists active forwards; p adds one and d removes one. Quitting never hangs on a forward that is still connecting.
• Privileged features and feature entrypoints. A feature that declares privileged: true now runs the container --privileged, and feature entrypoints run at every container start, so features such as docker-in-docker work out of the box. privileged can also be set directly on a sandbox. Both are skipped with a warning on Apple container.

[sandbox.infra]
image = "mcr.microsoft.com/devcontainers/base:ubuntu"
[sandbox.infra.features]
"ghcr.io/devcontainers/features/docker-in-docker:2" = {}

• config-toml-spec skill: the complete reference for config.toml (every key, merge rules, ${…} variables), written for both people and agents.

Fixed

• ${devcontainerId} in feature mounts resolves to the instance id. Per-instance volumes are deleted on rm and kept on rebuild.
• A sandbox mount on the same target now replaces a mount inherited from a template, instead of Docker rejecting the duplicate.
• Nested mounts are applied parent-first on every runtime, not only on Docker.

Internal

• run.rs and the TUI app.rs are split into per-concern modules. Docker-dependent tests are now required to pass on CI.

0.3.3

Release pipeline only: npm packages are now published with npm trusted publishing (OIDC) instead of a long-lived token. No changes to the CLI.

0.3.2

The npm root package is renamed to devsandboxes, because npm rejected devsandbox as too similar to an existing package. The installed binary is still called devsandbox.

npm i -g devsandboxes
npx devsandboxes --help

0.3.1

The CLI is now published to npm, so a Rust toolchain is no longer needed to install it. Prebuilt binaries ship as per-platform packages (linux x64/arm64, macOS arm64, windows x64), and the package also has a typed Node API.

The root package was renamed to devsandboxes in 0.3.2; install that version or later.

0.3.0

ssh-agent forwarding no longer needs a socket bind mount. A small static helper (devsbd) is embedded in the release binaries, installed into each container, and relays the host agent over exec stdio. This works on every runtime, including Apple container, and keeps working when the host agent socket changes.

Added

• Relayed ssh-agent forwarding through the embedded devsbd helper, used by default. Relays detect wedged connections with keepalives and handshake timeouts, and restart the daemon if the container was restarted outside devsandbox. git over ssh works inside postCreateCommand and the other lifecycle commands.
• devsandbox vscode <name> attaches VS Code to an instance from the CLI, using the same launch path as the TUI’s o key.

devsandbox vscode web

Changed

• Release archives (and later the npm packages) embed the helper. cargo install builds don’t, and fall back to the bind mount, which works only on Linux docker/podman.
• The TUI manages ssh-agent bridges on a worker thread, so the dashboard never blocks on them.

0.2.4

Fixes the Windows build, which broke the 0.2.3 release: 0.2.3 has no published binaries, so this is the first release that ships its changes. Also clarifies the docs.

0.2.3

ssh-agent forwarding, worktrees that start from the remote’s default branch, and process signalling from the dashboard.

This tag never got a GitHub release (the Windows build failed); its changes shipped in 0.2.4.

Added

• ssh-agent forwarding. The host SSH_AUTH_SOCK reaches every instance through a per-instance symlink mount, and start re-points it before the container starts. Forwarding therefore survives reboots and re-logins without a rebuild. exec sets SSH_AUTH_SOCK on every session. rm removes an instance’s link and gc removes orphaned ones.
• Worktrees start from the remote’s default branch. Instead of branching from whatever is checked out in the base repo, run fetches origin and branches from origin/HEAD (or main/master), without touching the base checkout. Use run --base or worktree-base to pick a different start point.

[sandbox.api]
folder = "../api"
worktree-base = "origin/develop"

• TUI process rows can be signalled: t sends SIGTERM and K sends SIGKILL to the selected pid. x closes an exited terminal where it is.

Fixed

• Process listings use pids from the container’s namespace, so signals reach the right process. Images without ps fall back to docker top and are shown as not signalable. The listing no longer includes its own ps process.

0.2.2

Renames no longer lose per-instance state, feature mounts are applied, and rebuild --force is added.

Added

• rebuild --force recreates an instance even when no drift is detected. Use it to pick up devsandbox-side changes that the config hashes can’t see.

devsandbox rebuild web --force
devsandbox rebuild --all --force

• Feature-declared mounts are applied, such as the host docker socket from docker-outside-of-docker. A sandbox mount on the same target overrides the feature’s, and mounts the host can’t satisfy are skipped with a warning.
• Persistent instance ids. Everything tied to an instance (${instance} mounts, worktree dir, shell history, isolated services) is keyed by an id that never changes, so renaming an instance is purely cosmetic.
• TUI prompt completion is driven by the same spec table as parsing, so every flag completes (including rebuild --force).

Fixed

• Shell history survives in VS Code terminals: HISTFILE is pinned in the rc files, not only in the container env.
• rename requires the exact instance name and no longer hangs the TUI.
• Missing instances can be rebuilt from the TUI.

0.2.1

Packaging only: the crate gains a description and the MIT license so it can be published on crates.io, and docs are excluded from it.

cargo install devsandbox

0.2.0

Instance lifecycle commands (start, stop, rebuild, rename), an integrated terminal in the dashboard, JSON output for scripts, drift detection for dockerfiles and services, and Apple container support.

Added

• Separate lifecycle verbs. run always creates a fresh instance. start / stop resume and suspend existing ones (--all for every instance), and rebuild (alias recreate) applies config changes in place while keeping the worktree, branch and per-instance state.

devsandbox run web --branch me/login-fix
devsandbox stop --all
devsandbox start web
devsandbox rebuild --all        # recreate every drifted instance

• Integrated terminal in the TUI: t opens a shell in the selected instance (zsh when available, otherwise bash) in its workspace folder. Terminals open as tabs; [/] cycle between them, x closes one, ctrl-]/F12 leaves the terminal, and mouse scrollback works.
• Machine-readable output. status --json prints the full dashboard snapshot in a versioned envelope, and ps, ls, stats, inspect accept --json (contract in docs/json-output.md).

devsandbox status --json | jq '.data'
devsandbox ps --json

• Service drift and rebuild. Editing a dockerfile now counts as drift, for sandboxes and services alike. service rebuild <name> recreates a service and rewires running sandboxes without restarting them, and service ls lists services like ls lists sandboxes. Drifted services are marked in the TUI and can be rebuilt from there.

devsandbox service ls
devsandbox service rebuild postgres

• rename (CLI and r in the TUI), plus logs, inspect, stats subcommands that work the same on every runtime.
• shell-rc: host shell snippets sourced by the container’s ~/.zshrc/~/.bashrc.

[template.base]
shell-rc = ["rc/aliases.sh"]

• Configurable worktree branch via worktree-branch (supports ${instance}) or run --branch.
• Apple container is supported as a runtime.
• TUI: coding-agent processes are highlighted in the process tree, and the detail panel shows an agent count.
• A devsandbox-cli skill that teaches coding agents to drive the CLI.

Fixed

• Worktrees are created under the config dir instead of the base repo, and a branch name that already exists is rejected with a clear error.
• The base folder is reused correctly once its direct-mount instance is removed.

0.1.1

First release. devsandbox runs devcontainer-style sandboxes directly on docker/podman from one config.toml, with no devcontainer CLI and no daemon.

Highlights

• devcontainer semantics in TOML. Sandboxes use devcontainer property names (image, build, mounts, containerEnv, remoteUser, the lifecycle commands, VS Code extensions…). Unknown keys are a hard error. extends composes reusable templates: tables merge, arrays concatenate.
• Native devcontainer features. Features are fetched from their OCI registry and baked into a derived image, without the devcontainer CLI.
• Concurrent instances of one repo. A second run of the same folder gets its own git worktree and branch, so instances never share a checkout. Instance names are deterministic (web, web-2, …).
• Services. Sidecar containers are reachable by name. scope = "isolated" (the default) gives each instance its own copy; scope = "global" shares one per project. gc removes the ones no instance uses.
• Shared caches and state. caches shares package caches across instances, persist-shell-history keeps a per-instance history, and ${sharedVolumes} / ${instance} place other state per instance.
• Config drift detection. Each container records a hash of its merged config, so an edited config shows up as drift.
• VS Code. Attach to an instance as a named workspace, with extra roots from folders and remoteUser honored.
• TUI dashboard (run devsandbox with no arguments): a tree of sandboxes and instances with live CPU/memory, a process tree for each instance, a services view, a config explorer (original vs resolved, next to docker inspect), logs, and a : command prompt with history and completion.
• Static release builds for Linux (musl), macOS and Windows.

[services.postgres]
image = "postgres:16"

[template.base]
caches = ["pnpm", "cargo"]
persist-shell-history = true
[template.base.features]
"ghcr.io/devcontainers/features/node:1" = { version = "lts" }

[sandbox.web]
extends = "base"
folder = "../web"
image = "mcr.microsoft.com/devcontainers/base:ubuntu"
services = ["postgres"]
postCreateCommand = "pnpm install"
folders = { "/workspaces/shared-lib" = "../shared-lib" }

devsandbox run web             # first instance mounts ../web directly
devsandbox run web             # second instance: web-2, on its own worktree
devsandbox exec -it web-2 zsh
devsandbox rm web-2

Source: CHANGELOG.mdEdit this page on GitHub(opens in a new tab)