Subshells
What a subshell is, how to launch one, and how attach, detach, restart and terminate behave.
A subshell is a real CLI agent (Claude Code, opencode, Codex, Hermes, Pi, or a plain terminal) running in a tmux pane on a machine you have enrolled. It lives on that machine, not in your browser: launch one, close the tab, and the process keeps working. Open it again from any device and you are back at the same live session. This page is the whole life of one: launching, attaching, restarting, and the difference between the two ways it can end.
Launching one
From the new-subshell form you choose an agent and a folder. That is all a launch requires. Everything else is optional:
- a preset: saved launch settings for that agent (see Presets),
- a machine: which node runs it; the pickers default sensibly, and the row disappears entirely when the control plane is the only machine you may launch on (a lone agent node keeps the choice visible),
- a name: an unnamed subshell gets a date/time label,
- a starting prompt: typed into the pane once the agent has drawn its first screen; the launch response tells you honestly whether it landed.
The agent must be installed and enabled on the machine you launch to, and the folder must exist and pass that node's directory allowlist, if it has one.
Names deserve one paragraph of their own: while a name is unlocked a subshell adopts the title its pane carries; even a placeholder name gets replaced, and agents like Claude Code rename themselves after the current task, which you see. Renaming it yourself locks the name permanently, yours from then on.
Attaching and detaching
Opening a subshell connects your terminal view to the pane: recent output is replayed first, then the live stream follows, and your keystrokes go through verbatim. Navigating away or closing the window simply detaches; the pane does not notice. Attach from another device as often as you like; several can watch the same pane at once, and Devices explains what happens to the pane's size when they do.
What the status means
Every list and card shows one of six states:
| State | Meaning |
|---|---|
| working | running, with output in the last minute |
| idle | running and quiet |
| waiting for you | the agent said it stopped and needs you; see Notifications |
| exited | the pane's process is gone; the subshell is still here and restartable |
| node unreachable | the machine that owns this pane has no connection to the server |
| ended | retired with the terminate action; still restartable |
node unreachable outranks all of it on purpose. Absence of a connection is not absence of a process: the node may be down while its panes keep running, and while the node is unreachable nobody knows what they are doing. So a subshell on a quiet machine says "node unreachable" and never "crashed". When the node reconnects the plane re-probes it, surviving panes answer, and the books are corrected.
Restarting
Restart runs the same subshell again in place: same id, same name, same place in every workspace. The pane is killed and relaunched in the same folder with the same settings; its credentials rotate (the old process's key dies with it and the new pane is launched with a fresh one), and when the agent's conversation transcript survived, the restart resumes that conversation rather than starting a new one. A restart always supersedes the auto-restart ladder (see below), so you can intervene at any point and get an immediate start.
Auto-restart is not a property of a subshell you set by hand; it is inherited from the preset the subshell was launched with. When a pane dies on such a row, the server brings it back on a rising delay (30 seconds, doubling, capped at 8 minutes between tries) and gives up after five consecutive failed attempts; a subshell that will never come back has its credential revoked rather than left alive. An offline or under-maintenance node defers the restart instead of failing it: the pane revives on schedule once the machine returns.
How it ends: terminate and Close
The two endings are different acts, and only one is offered to people:
- Close (the subshell's ⋯ menu, or a maximized pane's Close button) stops the process, removes the subshell, and deletes its stored transcript immediately. It asks for confirmation because nothing survives it.
- Terminate stops the process and keeps the subshell (the row, its name, its history) as an
endedentry you can restart. It is the verb agents use through the MCP tools; the human UI folded it into Close, because stopping-without-deleting has no everyday use case for a person.
Either way, a dead process's credential is revoked immediately; a running one's is never revoked by your browser closing.
Where transcripts live
Every pane is streamed to a log file on its own machine: that file is what makes replay-after-attach work, and it holds everything that was typed, including pasted tokens. Logs of subshells that are no longer running are removed after a retention window (30 days by default on the control-plane host; on a node its own sweep runs with a 1-day default); closing one removes its log on the spot.
See also
- First subshell: launching one end to end
- Workspaces & Panes: several subshells side by side
- Sharing: who else can see or drive it
- Notifications: being told when it waits for you
Last updated on