Subshell Docs

Manage a node

Inspect a node's runtime and execution settings.

Open the node

In the server dashboard sidebar, open Settings → Nodes, select a machine, and open Overview. Check its online state, maintenance state, runtime, and installed harnesses before launching work.

The harness list on a node's page is cached from its last detection, so it may describe an older state. Use Re-check to request fresh detection.

When a harness CLI is missing, its row offers Install on an enrolled node. The node's owner, a Manage grantee, or an Edit grantee can press it, the same band Update uses; the plugin's built-in installer runs on that node, as the user the subshell daemon runs as, under the same ten-minute bounded runner as the other harness commands, and the result appears on the row. When a harness CLI is installed, its row offers Update, which runs that tool's own update command on the node; Update all runs them one at a time. On the server's own node, only an admin sees Install and Update, because those commands run in the server's process. A running subshell keeps the version it launched with, shown on its page. Updating never restarts a running subshell.

The overview shows the operating system, release, architecture, hostname, CPU model, logical CPU count, and total memory when available. These describe host capacity, not current free resources or container limits. Offline nodes show how long ago they were last seen, or that no connection has been recorded, and retain their last known specs. MCP exposes the same hardware report through list_nodes; see MCP tool reference.

Cross-agent guidance

On the node's Overview page, find Cross-agent communication. The node's owner or someone they gave Manage can edit this guidance; a server admin manages it for the server's own node.

  1. Fill in Notes for calling agents with context that helps an agent choose and use this machine. For example: “Use this node for Linux builds; run tests with Bun.” Notes accept up to 8,000 characters.
  2. Select Save guidance to save the notes.
  3. Under Recommended starting directories, select Add directory, enter or browse to an absolute path, then select Add directory again to save it. Repeat for other suggestions. Use the remove button beside an entry to remove it.

Adding or removing a directory also saves any pending notes. Agents read both fields through MCP discovery. Directory suggestions don't grant or restrict access; the node's Directory restrictions still apply.

Apps, browsers, and virtual displays

The node's owner or a Manage grantee controls web previews and virtual displays independently; an administrator manages the server's built-in node. Follow Preview prerequisites and setup for the opt-in controls, access requirements, display providers, and the effects of changing settings.

Linux virtual display setup

Follow Linux virtual displays to install dependencies on the node, check readiness, and launch a screen for your subshell.

macOS display helper

Follow macOS virtual displays for BetterDisplay requirements, local helper consent, macOS permissions, and shared-desktop limits.

Enable the helper on the Mac before requesting a virtual display from that node.

Update the helper through an updated desktop app, including the steps to quit a running helper before replacing it.

Use and stop the display explains window placement, input limits, immediate disable, and sign-in behavior.

Names and ownership

Node names are display labels. Renaming a node doesn't change its identity, and launch pickers use the current display name.

The server host's node is named Server by default. Its internal ID remains local even if the administrator chooses another label.

Node owners manage the machine's settings. A share may allow launching there without granting ownership of service, directory, or enrollment controls.

Outgoing SSH

In the server dashboard, open Nodes, select your node, and find the SSH card on its overview. Allow SSH lets Subshell make outgoing SSH connections from this node and use its SSH agent to supply keys to other nodes. It doesn’t enable incoming SSH access to the node.

Only the node's owner or a Manage grantee can change this setting. An administrator manages it for the built-in node on the server host. Turning it off prevents new outgoing connections and stops the node from supplying keys, including to active connections.

You can also enable it when starting an SSH subshell: the connection form explains the change before you submit. See Connect over SSH.

With SSH allowed, the card gains Allow wide port forwards. While it's off, local and dynamic port forwards bind the node's own loopback address, so only programs on that node can use them. Remote forwards listen on the SSH destination under its SSH server's policy. See Port forwards for examples and bind-address rules. Turning it on lets a launch bind a port other machines can reach, which routes their traffic through that connection. It's off by default and sits behind the same gate as Allow SSH; turning it off affects new launches, while forwards already running keep going until their subshell closes.

Service and logs

Where you have management access, review the service and log sections. A node may be online from a terminal process even when no service is installed.

The Service card shows Start or Stop, and Install service or Uninstall service, based on the node's reported state. Restart is available when a service manager runs the node. Stop and uninstall sit on the Manage rung: the node's owner, or someone they gave Manage, can press them.

Restart, Stop, and Uninstall service ask for confirmation before making changes. The dialog explains whether subshells may close and whether you'll need access to the machine to bring the node back.

On the machine, use:

subshell status
subshell service status

status describes the daemon's recorded state; service status asks the service manager. Avoid status --probe during normal inspection because it connects as the node and can displace a running connection.

Next steps

See Node maintenance, Node services, and Node troubleshooting.

Edit on GitHub

Last updated on

On this page