Glossary

Three of these words are load-bearing, and one style rule governs all of them: no word names two things. "Server" is the control plane, never a machine that runs agents; "node" is a machine that runs agents, never an app; "client" is what a person points at a control plane, never the node daemon. The display labels ("Subshell Server", "Subshell Client", and the control-plane host's node row) sit on top of these words without changing them.

Terms

Attention state. What a pane's harness reports about its moment: a turn completed, or the agent needs you (a permission prompt, a question). Attention is why notifications can say "Done, waiting for you" instead of ringing on every output line. → Notifications

Assistant window. The one window of the Subshell Server desktop app that is allowed to drive the machine: first run, recovery, updating the bundled server, and reset. Everything else the app shows is the server's own page. → Install Subshell Server, Reset

Channel. A durable room where subshells talk to each other through the MCP tools, end-to-end encrypted so the control plane stores only ciphertext it cannot read. A nudge is the narrow exception worth knowing: it writes one fixed, server-generated line into the recipient's pane to ring the door, and the message itself stays behind read_channel. → Channels

Client. A person's interface to a control plane: the web UI, the mobile companion, the Subshell Client desktop app. A client calls the API; it never runs agents. → Mobile and tablet, Subshell Client as a node

Config home. The directory each binary keeps its settings in: ~/.config/subshell-server for the control plane (its config.env lives here), ~/.config/subshell for the node (its config.json, the node key's only home). → Files & Paths

Control plane (server). The one process that serves the web UI, holds the database, and makes every decision: what runs, with what credentials, on which machine. In this documentation "server" always means this, never a machine that runs agents; the machine running the control plane is also a node when it hosts panes, and the docs say so. → What is Subshell, Server overview

Data directory. Where the control plane keeps its working state (the pane logs, backups, plugin store, node artifacts, the update transaction), defaulting to the database file's own directory. The node has its own, under its config home. → Files & Paths

Everyone grant. Two related defaults, one per axis: the control-plane host's node row starts shared with edit to every signed-in user (removing that row's share is how an admin narrows the host down), and a subshell's sharing picker can grant to all signed-in users at once. Both are shares like any other: revocable, and invisible to no one who can see the row. → Sharing, Sharing a node

Harness (harness plugin). The agent CLI a subshell runs (Claude Code, Codex, OpenCode, Hermes, Pi), or, for a plain shell, the terminal plugin. A harness plugin is what teaches the control plane to drive one of them: the command line to build, the binary to look for, how to resume. The control plane owns which plugins exist; one install arms every node. → Agents overview, Build a harness plugin

Maintenance mode. A per-node flag that says: stay enrolled, keep answering every command, take no new subshells. Throwing it on from either end stops every subshell running on that machine, whoever owns them, and the owner is told by push. It is a routing preference, never a quarantine. → Maintenance mode

MCP (subshell mcp). The small stdio MCP server each subshell's harness spawns, one per pane, authenticated as that subshell and nothing else: it is how agents see their siblings, read channels, and launch work. → The subshell MCP server, MCP tool reference

Network plugin. A plugin that connects the control-plane host to one network (Tailscale, Headscale, NetBird, Cloudflare Tunnel) and publishes Subshell on it, which is what makes the address you used to discover the instance a trustworthy one to sign in from. It describes; the host executes. Privileged steps are printed, never run. → Network plugins

Node. A machine that runs agents: the subshell daemon and nothing else, with no UI, no database, no opinions. Registering one delegates command execution under its OS user to the control plane, which is the feature; the node's own key, by contrast, is near-powerless. → What a node is

Node key. The bearer credential an enrolled node dials its WebSocket with. On purpose it can do nothing on the REST API: its entire reach is impersonating that one node on its one socket. Rotating it revokes the live connection. → What a node is, Managing a node

Pane. The tmux split a subshell's harness actually runs in. A workspace is an arrangement of panes; each pane holds exactly one subshell, and the browser sees the pane, not the machine. → Workspaces and panes

Preset. Saved launch settings for one agent: environment variables, command-line flags, a settings blob the plugin understands, an auto-restart choice. Always optional: a launch needs only an agent and a folder. → Presets

Server. See control plane. This word names the control plane in these docs, in product names, and in subshell-server; the desktop app is "Subshell Server", the machine a node is not a "server".

Setup key. The single-use, 24-hour key (nsk_…) that enrolls a node. It stays listed in full on the Setup keys list until it is used, expires, or is revoked. The server keeps it in plaintext to make that possible, bounded by the credential being one machine, one use, one day. It is the enrollment credential: minting is gated by an admin toggle, and flipping that toggle off bounds the future without invalidating keys already handed out; deleting them revokes. → Add a node, Registration and enrollment

Share (view / edit). The two levels a subshell or node owner grants: view is read-only (list, detail, live terminal you cannot type into); edit adds interacting and managing (typing, rename, restart). Deleting and re-sharing stay with the owner, admins included; on a node, any share, even view, lets the grantee launch their own work there. → Sharing, Sharing a node

Subshell. One agent session: a real CLI harness running in a tmux pane on a machine you enrolled, private to its owner by default, attachable from any device. Closing the tab detaches; the pane keeps working. → Subshells, Your first subshell

System API key. A long-lived bearer credential an admin mints under Server Settings → API keys for machines that act on the instance as a whole: full access within, refused on admin surfaces, revoked by disabling. Distinct from the short-lived per-subshell tokens. → System API keys

Trusted origins. The set of addresses a browser may use to sign in: derived live from the instance's own addresses, the operator's extras (TRUSTED_ORIGINS), and any network plugin's published record, never from the request's own Host, which is the DNS-rebinding hole the list exists to close. → Networking

APP_BASE_URL. The address the instance calls itself: cookie and redirect base, the URL baked into install and enroll flows, and, because better-auth derives it from here, the passkey rpID. Changing it moves which host passkeys work on. → Networking

Workspace. A saved arrangement of subshell panes: several agents side by side, stored on the instance, reachable from any device (tiles on a wide screen, tabs on a narrow one). → Workspaces and panes

See also

• What is Subshell: the vocabulary taught in context.
• subshell-server CLI and subshell CLI: the two binaries behind the words.
• Environment Variables: where each setting lives.

Edit on GitHub