Run devsandbox with no arguments on a terminal and the dashboard opens (Linux and macOS: it works through the host daemon, which it starts). The preview next to the text follows along as you scroll: it shows what each section talks about. Click it and press the keys each section suggests; everything in it is fake, nothing runs.
Instances
The Instances tab lists each sandbox of your config with its instances under it. The first instance mounts your checkout; each repeat one has its own git worktree (⎇ .worktrees/web-2). Detail, below the table, shows the selected row.
Try ↑ ↓ to move, or click the ▾ web row for the sandbox itself.
Services
Tab 2 lists the service containers your sandboxes use: shared by every instance (global) or one per instance, and who uses them.
Try enter for the service’s config, 1–4 or ← → to switch tabs.
Config explorer
enter opens the selected sandbox’s config as written in devsandboxes.toml, next to the docker inspect of its container. t flips to the resolved config, with templates and extends merged in.
Try t to toggle, ↓ to scroll, esc to close.
Run, stop, start
r on a sandbox row prefills :run web: Enter starts a new instance, on its own worktree. run, rebuild and start run in the background, in the host daemon, and keep going if you quit the dashboard: the new row’s status shows the step it’s at (building, postCreateCommand, …), and b opens its build log, following along. d on a row still building offers to cancel it (a cancelled run is undone). s stops the selected instance, or starts it again the way devsandbox start does, postStartCommand included. stop and rm run in the daemon too; the status line says when they’re done. On an instance row, r renames it.
Try enter to run web-4 and watch its row go from building to running, then ↓ to it and b for its build log, or s on any instance.
Logs
l shows the last 50 lines of the instance’s container log.
Try ↓ to scroll, g / G for top and bottom, esc to close.
Terminal
t opens a shell in the selected instance, inside the dashboard: the bottom half splits into Detail and the terminal, one tab per shell. While the terminal has focus, every key goes to the shell. ctrl-] (or F12) goes back and forth.
Try type ls and enter, esc back to the dashboard (ctrl-] in the real one), ↓ t for a second shell, esc again, then [ ] to switch and x to close.
Port forwards
p prefills :port web: add a port and Enter, and it’s on 127.0.0.1 on your machine. Forwards show in the Ports tab and are kept by the host daemon, so they outlive the dashboard and come back on the same host port after a restart, until d stops one. A sandbox’s forwardPorts are forwarded for you while its instance runs. p on a machine’s row works too: the port opens here, tunnelled over ssh. Linux and macOS hosts.
Try d to stop it, then 1 p, type 8080:3000 and enter.
VS Code
o opens VS Code attached to the instance’s container, with the sandbox’s extensions. See the VS Code example for the setup.
Try ↓ o to open it on web-2; esc closes it (only in the preview).
Inbox
A script or an agent in a sandbox reaches you with devsbd notify "tests pass". It lands in the Inbox tab (4), with a count in the tab and a ✉ on the instance row, and pops up on your desktop. A sandbox with inbox = true (typically a dispatcher) can also keep one thread per item there: cards on the left, the selected thread always open on the right, ←/→ to step through Needs you / Active / Done / All, and enter to focus the thread. The thread’s header stays pinned at the top (state and status, its buttons), any open form sits under it, and the conversation below runs newest first: the sandbox’s messages, your replies and answers. The reply box at the bottom grows as you type and says what sending does. The mouse works there too: click a card, a view name, the thread, a form question or the reply box; the wheel moves through the cards or scrolls the thread. You can answer from a shell too, with devsandbox inbox.
Try 1 for Instances: leaving the Inbox marked it read, so web-3 lost its ✉.
Command prompt
: opens a prompt for the CLI’s verbs: run, exec, rm, rename, stop, start, rebuild, port, code. Tab completes commands, sandboxes and instances; rm asks before deleting a worktree’s branch.
Try tab to cycle, type -3 and enter to remove web-3, then y or n.
Help
? opens Settings & help: a few settings on top (space toggles, saved for next time) and every key below; q quits the dashboard.
Try esc or ? to close.
Arrow keys or j and k select an instance, o opens it in VS Code, Escape closes VS Code, t opens a terminal on it, s stops or starts it, d removes it (or cancels its build), l shows its logs, b its build log, p forwards a port, Enter opens the config explorer, colon opens the command prompt where Tab completes and Escape cancels, left and right arrows or 1 to 4 switch tabs, question mark shows help. In a terminal, keys go to the shell and Escape returns to the dashboard; square brackets switch terminals and x closes one. Tab leaves the preview.
devsbd notify "…"- ↑/k ↓/j
- move selection
- tab 1-4
- switch · jump to tab
- enter, e
- config explorer
- :
- command prompt
- r
- run / rename
- o
- open in VS Code
- s
- stop / start
- l
- logs (Instances)
- b
- build log (Instances)
- p
- forward a port
- d
- rm / cancel build (Instances)
- d
- stop forward (Ports)
- t
- open terminal
- [ / ]
- prev / next terminal
- x
- close terminal
- ctrl-]
- terminal ⇄ dashboard
In this preview ←/→ switch tabs (Tab leaves it; click a tab instead), esc closes VS Code or leaves a terminal, and the ▾ web row is picked with a click. In the : prompt Tab completes; in the config explorer t toggles original / resolved.
esc or ? to close
Other machines
With machines registered, the dashboard shows their sandboxes and instances too, with a MACHINE column (blank for this host’s). Every key works on their rows, terminals included (over ssh -t), and : commands take my-server/web-2. A machine that’s down keeps its last rows, shown unreachable; one not reached yet is a note in the header. p forwards a port from a machine’s row to this host, listed in the Ports tab with its MACHINE. o (VS Code) doesn’t work on a machine’s rows yet. A Machines tab (5) lists every registered machine: its ssh target, whether it’s connected (and why not), whether your ssh agent reaches it, and its devsandbox version; a turns that agent relay on or off for the selected one, no prompt.
Every key
The real dashboard’s keys, also in its ? screen. The Preview column says what the preview on this page fakes. Clicking a tab title switches to it, like 1–5. Dragging selects text and releasing copies it (copy on select, on by default; turn it off in ? to copy only with ctrl-shift-c, or ctrl-c in terminals that keep ctrl-shift-c for themselves, as the dashboard tells you); an app in the integrated terminal that uses the mouse (vim, tmux) gets the drag and hover instead, and what it copies reaches your clipboard (terminal clipboard in ? turns that off). Copies go out as OSC 52, and a dashboard running on your own machine also hands them to pbcopy, wl-copy or xclip, so they land in terminals that ignore OSC 52, like iTerm2 by default.
Everywhere
| Key | Action | Preview |
|---|---|---|
tab / shift-tab |
Next / previous tab | ← → instead (Tab leaves it) |
1–5 |
Jump to a tab (5: Machines, with a machine registered) |
1–4 |
: |
Command prompt | yes |
? |
Settings & help: space / enter / click toggles a setting, tab moves between them |
help only |
q, ctrl-c |
Quit | no |
| drag | Select text in one pane; release copies it while copy on select is on (the default) | no |
ctrl-shift-c, cmd-c |
Copy the selection to your clipboard; ctrl-c too over a dashboard selection, for terminals that send it plain or keep ctrl-shift-c (Alacritty, GNOME Terminal, kitty, …) |
no |
shift-drag |
Your terminal’s own selection (whole rows, across panes) | no |
Instances and Services
| Key | Action | Preview |
|---|---|---|
↑ k / ↓ j |
Move the selection | yes |
→, space |
Expand a sandbox’s instances, an instance’s processes | no |
← |
Collapse, or jump to the parent row | no (switches tabs) |
enter, e |
Config explorer | yes |
r |
Run (sandbox row) / rename (instance row) | run only |
s |
Stop / start | yes |
l |
Logs (Instances) | yes |
b |
Build log (Instances): follows a build in flight | yes |
p |
Forward a port (instance or service) | yes |
o |
Open in VS Code (Instances) | yes |
d |
Remove the instance now, no prompt; cancel it, after a y/n, while it’s building (Instances) |
no |
t / K |
SIGTERM / SIGKILL (process row) | no |
Ports, Machines and Inbox list
| Key | Action | Preview |
|---|---|---|
d |
Stop the selected forward (Ports) | yes |
a |
Turn the selected machine’s agent on / off (Machines) | no |
← → |
Step the views: Needs you / Active / Done / All (Inbox) | no |
enter |
Focus the selected thread (Inbox) | no |
r / i |
Focus the reply input, when the thread takes replies (Inbox) | no |
d |
Dismiss a notification / mark a thread done (Inbox) | no |
u |
Reopen a done thread (Inbox) | no |
D |
Clear all notifications (Inbox) | no |
Inbox thread
The selected thread’s pane sits to the right of the list, always open; these keys apply once it (or its form or reply input) has focus.
| Key | Action | Preview |
|---|---|---|
esc |
Back to the list (input or form → thread → list) | no |
enter |
Open its link | no |
1–9 |
Run a button; one on a stopped instance starts it first | no |
↑ ↓, pgup pgdn, g / G |
Scroll the conversation (g: newest) |
no |
tab |
Focus the open form, else the reply input | no |
r / i |
Focus the reply input | no |
d / u |
Mark done / reopen | no |
o t l p |
VS Code / terminal / logs / forward on the thread’s instance (starting it first if it’s stopped, except logs) | no |
m |
Show the markdown source instead of the rendered text (every thread, until you quit) | no |
enter (input) |
Send the reply; it stays open, empty, for the next one | no |
alt-enter (input) |
New line (shift-enter too, where the terminal reports it) |
no |
Inbox form
An open form is pinned under the thread’s header. Your answers are saved as you go, so you can leave and come back, from this dashboard or another.
| Key | Action | Preview |
|---|---|---|
tab / shift-tab |
Next / previous question | no |
↑ ↓ |
Move over the options | no |
space |
Pick an option (toggle, when several can be picked) | no |
e |
Edit a text answer in the reply box; enter or esc keeps it, alt-enter adds a line |
no |
enter |
Confirm: shows what will be sent (or what’s missing); enter again submits |
no |
esc |
Cancel the confirm, else back to the thread | no |
Terminals
| Key | Action | Preview |
|---|---|---|
t |
Open a terminal (instance or service) | instances only |
T |
Force a new terminal for the same target | no |
[ / ] |
Previous / next terminal tab | yes |
x |
Close the active terminal | yes |
ctrl-], F12 |
Terminal ⇄ dashboard | also esc |
Config explorer and logs
| Key | Action | Preview |
|---|---|---|
t |
Original / resolved config | yes |
tab |
Switch pane (config ⇄ inspect) | no |
< / > |
Resize the divider | no |
↑ ↓, pgup pgdn |
Scroll | yes |
g / G |
Top / bottom | yes |
esc, q |
Close | yes |
Command prompt
| Key | Action | Preview |
|---|---|---|
tab |
Complete / cycle | yes |
↑ ↓ |
History | no |
ctrl-u ctrl-w |
Clear line / delete word | no |
esc |
Cancel | yes |
Source: site/src/content/docs/dashboard.mdxEdit this page on GitHub(opens in a new tab)