Host daemon.

devsandbox serve is a small background process, one per user, that holds the live side of devsandbox on your machine: the run, rebuild, start, stop, rm and service rebuild you start, everything the dashboard shows, the connection to each running sandbox’s helper, the ssh-agent relay, port forwards, desktop notifications, the control commands dispatchers use, and the API other tools talk to. Because it lives outside the dashboard and your terminal, all of that keeps working when you close them.

You don’t start it

The dashboard, run, rebuild, start, stop, rm, service rebuild and the commands that relay your ssh-agent start it when it isn’t running, and a newer devsandbox takes over from an older one by itself. It exits 10 minutes after its last user left: no dashboard, no build or other command still running, no port forward, no running dispatcher or inbox = true sandbox. Files stay the source of truth (state.toml, the Inbox), so stopping it loses nothing, and read-only commands such as ps or devsandbox inbox ls don’t need it.

What it keeps across restarts:

• Builds. A run, rebuild or start keeps going when the daemon hands over to a newer one, and the next daemon picks it up. It runs with the environment of the shell that started it, not the daemon’s, so ${localEnv:…} and your ssh-agent are yours. With no daemon reachable, the command warns and runs in your terminal instead.
• Port forwards. Ports-tab forwards survive closing the dashboard and come back on the same host port when the daemon restarts; a sandbox’s forwardPorts follow its instance.
• Dispatchers. devsbd ensure, exec, events and the rest are served whether or not a dashboard is open. A control command exits 75 only when no daemon is reachable; scripts retry.

Other machines

The daemon can also manage sandboxes on other hosts you reach over ssh. machine add checks the machine’s devsandbox first: when it’s missing or another version, it 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 terminal). Register one, and its sandboxes and instances show in your dashboard next to yours, and the CLI finds its names:

devsandbox machine add me@my-server   # pick its config roots; or --config '~/sandboxes'
devsandbox run api                    # `api` is only defined there
devsandbox exec test                  # an instance there: ssh -t … devsandbox exec test
devsandbox stop my-server/test        # qualified, when the name exists here too
devsandbox ps --machine my-server     # a command without a name, run there
devsandbox machine ls                 # each machine's state: connected, unreachable, …

Your daemon connects to each machine’s own daemon only while something needs it (an open dashboard, a command), through the login shell there, so a build on a machine runs with that machine’s environment. Your ssh-agent reaches a machine only if you turn on its agent (devsandbox machine add --agent, devsandbox machine set <name> --agent on, or a on the dashboard’s Machines tab); then it’s relayed there while you use the machine, and turning it off takes effect at once. ssh never prompts: use a key from your agent. A machine that’s down keeps its last rows, marked unreachable. devsandbox port my-server/web 3000 opens a machine’s port here, over ssh (the machine needs this devsandbox version); a machine’s own forwardPorts stay on it. VS Code on a machine isn’t supported yet.

Start it at login

A sandbox the container runtime restarts on boot (autostart = "runtime") can’t start a host process itself, so until your first devsandbox command its control commands wait. Hand the daemon to your service manager to close that gap:

devsandbox serve install     # a systemd user unit (Linux) or a LaunchAgent (macOS)
devsandbox serve uninstall

The installed daemon never idles out and follows upgrades: a newer devsandbox repoints the unit at its own binary. Run install again after changing PATH or your container runtime’s settings. To only keep the daemon from idling, without a unit, set it in ~/.local/share/devsandbox/daemon.config.toml:

[serve]
keep-alive = true

Talk to it

Editors and GUIs reach the same Inbox, instances and forwards as the dashboard through a JSON-lines API: spawn devsandbox api --stdio, or use the typed client of the npm package, connect().

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