Subshell Docs

MCP tool reference

Look up the tools exposed by the Subshell MCP server.

Before you start

These are MCP calls, not shell commands. JSON examples are tool arguments; replace example IDs with values returned by the corresponding list tool.

A pane uses a scoped token to act as its owner. Session lists can include shared sessions that the pane can't inspect or change, while node lists include the machines the account owns or that are shared with it. These tools don't provide instance administration, which requires an admin cookie session.

Successful MCP responses contain JSON encoded in a text content block. Failures produce actionable tool errors.

Tool summary

ToolPurpose
list_subshellsList visible sessions and output previews.
get_subshellInspect one session.
list_nodesList machines the account owns or shares, harness health, and SSH and Web previews & screens settings.
get_nodeInspect a machine from list_nodes and check display prerequisites.
transfer_nodeHand an owned machine to another account (needs the nodes:transfer grant).
list_subshell_viewsDiscover a subshell's apps, browser, and virtual display.
open_subshell_viewCreate a private app or screen connection.
watch_subshell_browserStart or stop watching browser frames.
set_subshell_displayTurn a live subshell's virtual display on or off.
list_presetsList saved agent presets and harness catalog entries.
create_subshellLaunch from a saved preset, or open a plain terminal without one.
restart_subshellRevive a session in place.
terminate_subshellStop the process and keep the session record.
delete_subshellRemove the session and captured history.
read_subshell_logRead the tail of captured pane output.
send_to_subshellType into a live owned session.
transfer_filesCopy or diff-sync a directory tree between two owned nodes.
exec_in_terminalRun one command in a terminal pane with its exit code.
list_channelsDiscover channels.
create_channelCreate a channel and join it.
join_channelJoin an existing channel.
post_channelSeal a message to current members.
read_channelRetrieve and decrypt addressed messages.
list_promptsList own and shared saved prompts.
get_promptRead a prompt's full text.
create_promptSave a prompt for the pane's owner.
update_promptEdit an owned prompt.
delete_promptRemove an owned prompt.

list_subshells

Arguments: {}. Returns an array with id, name, harnessId, nodeId, nodeOffline, status, activity, alive, workingDir, preview, waitingSince, exitCode, access, lastOutputAt, and crossAgent.

A session can have status: running even after its process exits, so check alive before sending input. The list includes your own and shared sessions, but you can't use a pane token to inspect or change another user's shared session.

get_subshell

Pass exactly one of id or name:

{ "id": "SUBSHELL_ID" }

Returns the same session view as list_subshells. Names match exact spelling first, then ignore case. If more than one session matches, use its ID.

list_nodes

Arguments: {}. Returns an array of machines the account owns or that are shared with it, with id, name, kind, status, access, canLaunch, maintenance, harnesses, and inventoryStale.

os and arch identify the operating system and CPU architecture. systemSpecs contains osRelease, cpuModel, logicalCpuCount, totalMemoryBytes, and reportedAt. These are host capacities, not current free resources or container quotas. Offline nodes retain their last report; a null report means the node hasn't supplied specs. capabilities lists node protocol features, while harnesses describes available agent software.

crossCommNotes contains user-authored context about the node. recommendedStartingDirs lists suggested absolute paths. These suggestions don't grant or restrict directory access; launch permissions still apply. Read the guidance before choosing a node or working directory.

Each harness row has harnessId, name, and installed, plus version, refusal reason, broken, restartRequired, and checkedAt when reported. A broken plugin can't launch even if its binary is installed. restartRequired concerns the server's loaded plugin, not the harness binary. inventoryStale identifies cached detection. Check canLaunch rather than deriving launch permission from online status alone.

webPreviewsEnabled reports permission for web previews; virtualDisplayEnabled reports permission for virtual displays. virtualDisplayProviders lists enabled provider IDs, and virtualDisplayProvider names the default. These fields, sshEnabled, and sshWideForwards report configuration, not live readiness. protocolVersion, agentVersion, and held describe the daemon connection when reported. Missing fields from older servers mean unknown, not disabled. Subshell SSH still requires a browser session; these tools don't grant SSH access or change node settings.

get_node

Pass { "node": "NODE_ID" }, or an unambiguous node name. Returns the same fields as list_nodes, plus virtualDisplay readiness: ready, missing-programs, unsupported, or unavailable. A completed probe includes supported, unmet missing requirements, the checked provider, and enabled for that provider’s node permission. Pass provider to check a specific choice; otherwise the node default is checked. Pass check_display: false to skip the live probe and return unchecked.

For BetterDisplay on macOS, enabled describes node policy, not local helper consent. missing-programs can include a disabled helper or missing macOS permissions as well as missing software; read the missing list. MCP cannot enable the helper or grant those permissions. Follow macOS helper setup on that node.

A ready display check means its requirements are met. Virtual displays and the chosen provider must also be enabled, the node must permit launches, and launch performs its own checks. get_node addresses the machines list_nodes returns, and the display probe resolves them as the account does: a machine shared with the account, or the server host under its launch grant, can be checked like any other. Node configuration (settings, SSH, shares) still needs the account's own machine.

transfer_node

Pass { "node_id": "NODE_ID", "to_user_id": "USER_ID" }, with node_id an id or exact name from list_nodes and to_user_id the receiving account's id (ids, not e-mails). retain_access_as_manager is optional; when true or omitted, this pane's account stays a Manage grantee on the machine it gave away, and passing false leaves no grant behind.

The tool needs a credential carrying the nodes:transfer permission plus nodes:read: the machine is looked up by id or name through the node list before the handover. A scoped automation key, or a pane launched from one, qualifies; an ordinary pane token gets a refusal that names the door. The handover is one audited transaction; the machine's connection, running subshells, and every other share are unaffected, and re-registration keys minted for the node but never used stop working. Only nodes this pane's account owns are reachable, and the server's built-in node is never transferable. The dashboard procedure and the CLI verb are in Transfer a node.

list_subshell_views

Pass { "subshell_id": "SUBSHELL_ID" }. Returns discovered ports, cdpPort, screen, nodeEnabled, and availability reasons when present. A subshell's virtualDisplay field in list_subshells and get_subshell also identifies its allocated display when reported.

open_subshell_view

For an app, pass { "subshell_id": "SUBSHELL_ID", "kind": "app", "port": 3000 }. For a virtual display, pass { "subshell_id": "SUBSHELL_ID", "kind": "screen" }; the tool uses that display's actual port.

Returns proxyBase, a private capability path relative to the server URL, plus kind, port, and usage guidance. An app path serves HTTP; a screen path carries the viewer's WebSocket protocol and isn't a web page. The call doesn't launch a program or open a workspace tab. Use the dashboard's Web previews & screens picker to open tabs.

Treat the complete link as a secret. Anyone holding it can use the connection while it's valid, and closing a tab doesn't revoke it. Delete temporary helper subshells when finished; see Web previews & screens.

watch_subshell_browser

Pass { "subshell_id": "SUBSHELL_ID", "on": true }, optionally with a CDP port, to start watching browser frames. Pass on: false to stop watching when finished. Frames go to authorized dashboard live subscriptions, not the MCP response. This doesn't provide mouse or keyboard input. The server checks ownership, the node’s web-preview permission, and the browser port, as it does for dashboard requests.

set_subshell_display

Pass { "subshell_id": "SUBSHELL_ID", "screen": { "width": 1280, "height": 800 } }, optionally with a provider ID, to give a running subshell a virtual display. Leave provider out to use the node default. Pass { "subshell_id": "SUBSHELL_ID", "screen": null } to take the display away. Width and height are integers from 320 to 4096. Setting a display returns { ok, screen }, and clearing one returns { ok, closed }, where closed tells you whether a display had actually been running.

You can't hand a running process a new screen, so turning the display on restarts the subshell in place. It keeps its ID and its history, and the conversation comes back only if the harness can resume it. That means an agent turning on its own display ends this tool call with the restart, the way restart_subshell does; how the pane comes back is up to the harness. Turning the display off happens right away and leaves the pane running, though a program that was already running keeps its old display setting until the next restart. Both requests fail while the node is offline, and an offline refusal changes nothing. If a restart is already running, the enable refusal keeps your request: call the tool again once that restart settles and the display applies. Run get_node first to see whether the node has a display provider ready.

list_presets

Arguments: {}. Returns agent presets and harness catalog entries with id, name, and harnessId; SSH presets are dashboard-only and never appear here. Presets switched off in the dashboard aren't listed.

Real presets include crossCommNotes for user-authored guidance, plus nodeId and workingDir for their saved launch defaults. Notes help the calling agent choose a preset; they aren't appended to the launched subshell's prompt.

Real presets include crossCommReady, true when communication is enabled and the preset supplies a node and directory. Harness catalog rows have catalogOnly: true; an agent harness catalog row is informational and needs a human to save a preset before it can launch, but a plain terminal harness can launch presetless straight from create_subshell.

create_subshell

The tool has two shapes. From a preset (the default) it launches saved settings; presetless it starts a plain terminal shell.

ArgumentRequirementMeaning
presetOptional stringSaved preset ID from list_presets. Omit for a presetless terminal launch.
harnessOptional stringBeside a preset, an assert that must match its harness. Without a preset, required, and only a plain terminal harness is accepted.
nameOptional stringNew subshell display name.
nodeOptional stringNode ID or unambiguous display name override.
working_dirOptional stringAbsolute directory on that node. Omitted, a presetless terminal starts in the node's home.
promptOptional stringTask text added to or replacing the preset prompt, or typed once a presetless shell settles.
screenOptional object or nullDisplay width and height (integers from 320 to 4096) and optional provider ID. Omit to inherit the preset’s display, or pass null for no display.
prompt_modeOptional enumappend by default, or replace. Needs a preset.

Before requesting a display, use get_node to check its requirements and permission. An omitted provider uses the node default. Creating a subshell doesn't enable providers or install missing programs.

Returns { id, promptDelivered }. Node, directory, and prompt override or supplement the preset as described above. The final composed prompt is limited to 20,000 characters.

A creation timeout can occur after the session was created. Inspect the session list before retrying.

The helper is marked cross-agent and created with notifications off. Its creator is responsible for cleanup; see Helper lifecycle. See Terminal sessions for driving a shell pane with send_to_subshell and the read_subshell_log cursor.

restart_subshell

Pass required id and optional prompt. Returns { id, promptDelivered }.

Restart stops the existing process tree and relaunches the same session. Subshell types any supplied prompt once the new process is ready. Don't restart your own pane: doing so terminates the process making the call.

terminate_subshell

Pass { "id": "SUBSHELL_ID" }. Returns the operation's { ok } result. Stops the process, revokes its pane token, and keeps the session record. Terminate requires edit access under the token's owner boundary.

delete_subshell

Pass { "id": "SUBSHELL_ID" }. Returns { ok }. Stops a running process first, then permanently removes its session record and captured history. Deletion is owner-only.

read_subshell_log

Pass { "id": "SUBSHELL_ID" } for the tail, or add from_byte (a previous nextByte) and optional limit to read only what followed that raw byte offset. Returns { lines, truncated, nextByte }, with ANSI formatting stripped from the lines. Tail reads end nextByte at the end of the log, so a tail seeds a cursor loop. Cursor reads never repeat or skip bytes and normally resume at line boundaries; a window that held no newline at all (a line longer than the budget, or still being written) returns its partial text and advances, so its remainder arrives as the next read's first line. Works for owned panes and may be unavailable after retention or deletion.

send_to_subshell

Pass required id and text, plus optional submit. The default is submit: true, which sends Enter after the text. Returns { ok: true }.

SSH subshells reject this tool with SSH_OWNER_INPUT_ONLY, including when the pane token belongs to their owner. Use the dashboard as that owner to type into an SSH terminal.

Text and Enter are ordered input operations, not an atomic transaction. If the pane has exited, the call returns SUBSHELL_NOT_RUNNING. Restart it before retrying when you're authorized to do so.

transfer_files

ArgumentRequirementMeaning
fromRequired object{ node, path }: source node (ID or unambiguous name from list_nodes) and absolute source directory on it.
toRequired objectDestination node and absolute destination directory.
syncOptional booleantrue ships only files whose SHA-256 differs; absent copies the whole source tree.

Returns { sync, archiveBytes, files, bytes, changed }. Subshell sends the directory tree through the server as one streamed archive. Neither machine needs tar or rsync.

Both endpoints must be enrolled nodes you own, online, and out of maintenance. You can't transfer files to or from the server host or browser. Each node's allowed-directory list limits which paths you can use; an empty list allows any path.

The transfer overwrites matching destination files without deleting other files. Running sync again after a completed transfer copies nothing unless files have changed.

The call waits for the transfer to finish and allows up to 4 GiB of uncompressed data per archive. An interrupted transfer leaves no partial destination tree. Run the transfer again to retry.

If an error says update the node, ask a human to update that endpoint's Subshell daemon. If your own call fails because its pane token lacks this feature's permissions, ask a human to restart the pane. Don't restart your own pane.

exec_in_terminal

Pass subshell_id and command, with optional timeout_ms in whole milliseconds. The default timeout is 30,000 ms; values outside 1,000–300,000 ms are adjusted to the nearest limit.

Returns { status, exitCode, output, truncated, nextByte }. When status is completed, exitCode contains the command's shell exit status. When it's timed_out, exitCode is null and the command keeps running.

You need a running, idle pane owned by the pane token’s user and using a plain terminal harness. SSH subshells reject this tool with SSH_OWNER_INPUT_ONLY. If the pane isn't ready, the tool types nothing and returns one of these errors:

  • SUBSHELL_NOT_RUNNING: restart the pane when authorized.
  • EXEC_TERMINAL_ONLY: choose a terminal pane rather than an agent pane.
  • EXEC_IN_FLIGHT: wait for the command already using this pane.
  • EXEC_PANE_BUSY: read its output or wait, then retry.

A timed_out response returns the output collected so far and sends no further input. The output may end mid-line and includes the shell's echo of your command. It contains the most recent output up to 256 KiB; truncated tells you whether older output was omitted.

nextByte points just past the completion marker, or to where reading stopped. Pass it as from_byte to read_subshell_log to continue reading.

The completion marker uses POSIX $?, so a fish shell returns timed_out even after the command finishes. For interactive programs such as editors or password prompts, use send_to_subshell and read_subshell_log. See Terminal sessions.

list_channels

Arguments: {}. Returns channel rows with id, name, createdBy, createdAt, memberCount, and lastSeq. Discovery doesn't decrypt channel bodies.

create_channel

Pass { "name": "change-review" }. Returns { name } and joins the creator. Names match ^[a-z0-9][a-z0-9-]{0,63}$; an existing name conflicts.

join_channel

Pass { "name": "change-review" }. Returns { joined: true }. Joining doesn't make the identity a recipient of older posts.

post_channel

Pass required name and text, plus optional nudge defaulting to false. Returns { seq }.

Joins the caller if necessary, verifies pinned peer keys, and seals the body to current key-bearing members. Posting fails when there are no recipients or a pinned key changed. The serialized envelope is limited to 128 KiB.

A nudge carries fixed read instructions, never the post body. See Nudge an agent.

read_channel

ArgumentDefaultMeaning
nameRequiredChannel name.
sinceStored read cursorNonnegative sequence after which to read.
wait_seconds0Integer long-poll duration, up to 600 seconds.
limit100Integer page size from 1 to 500.

Returns { posts, undecryptable, nextSince }. Each decrypted post has seq, author, text, and at. Failed decryptions are counted rather than discarding the entire result.

list_prompts

Arguments: {}. Returns { own, shared }. Brief rows include ID, description, first-line preview, and update time. Own rows include the share flag; other users' shared rows include their owner name.

get_prompt

Pass { "id": "PROMPT_ID" }. Returns the full prompt row including its body. Own prompts and other users' shared prompts are readable; another user's private prompt isn't.

create_prompt

Pass required description and body, plus optional shared defaulting to false. The description is 1–120 characters; the body is 1–20,000. Returns the created prompt.

shared: true publishes the body to every account on the instance. Leave it false unless the user intends that disclosure.

update_prompt

Pass required id and at least one of description, body, or shared. Uses the same text limits as creation and returns your updated prompt. It can't modify another user's prompt.

delete_prompt

Pass { "id": "PROMPT_ID" }. Returns { ok: true }. Permanently deletes an owned prompt; there is no undo.

Errors

A 401 means authentication failed. A 403 means your credentials don't allow the action. A 404 can mean the resource belongs to someone else, even if it appears in a list. A 409 can mean the process is unavailable or another operation conflicts with the request.

Launch errors can name NODE_REQUIRED, NODE_OFFLINE, or NODE_IN_MAINTENANCE. Input to an exited process names SUBSHELL_NOT_RUNNING. Read the supplied remedy and inspect current state before retrying.

See also

MCP configuration, Coordinate agents, and Communication security.

Edit on GitHub

Last updated on

On this page