Installing Agent CLIs

A plugin teaches Subshell to drive an agent CLI; the CLI itself is a program you install like any other. When a launch picker says "program not found," the plugin is fine and the binary is missing. Subshell can run that machine's own installer for you: on one host, with one gate.

Where the button is

The in-page installer appears in two places, and both are admin-only surfaces:

• The Add an Agent screen of the first-run wizard, after you create the account.
• The Harnesses card of the control-plane host's node row ("Server" by default): a row whose binary is missing offers an Install button when you are an admin. Enrolled nodes never offer it; see the boundary below.

Each agent row shows its detection state, and beside the Install button, the exact command it will run, and no click is needed to find out what you are about to do.

What it runs, and how it runs it

The installer runs the agent's own vendor install command, the one baked into that plugin's built-in manifest, not a mirror maintained by us. The request to the server carries only which agent; which command exists is decided by what is compiled into this build. It runs:

• On the control-plane host, as the server's own OS user. It never reaches into a node's machine.
• Only for an admin. The route demands an admin browser session; bearer API keys are refused, and unlike the rest of first-run setup it is never open on an instance with no accounts, because letting an anonymous caller make the host fetch and run a remote script would be remote code execution. That is safe for the wizard: the screen sits after account creation, so whoever reaches it already signed in.
• Bounded. The installer gets an allowlisted environment (not the server's own, which holds secrets), the login shell's PATH added so package managers are reachable, a closed stdin, a 64 KiB cap per output stream, and a 10-minute deadline. One install runs per agent at a time.
• Live and audited. Installer output streams to the page line by line while it runs; when it exits, the result, exit code and output, is reported, the agent is re-detected so the row shows its new state immediately, and the run is written to the audit log with the admin who started it. No credential appears in the audit line.

An install that runs and fails is shown as a failure with the installer's own output under the row that failed: a non-zero exit is a result, not a mystery.

The commands, so you can run them yourself

The same commands work in any terminal on the host. These are exactly what the button runs for the six built-ins (Terminal installs nothing: every machine that runs Subshell has a shell):

After installing by hand, the row updates on the next page load; a Re-check asks that machine right now.

The boundary: this host only

The installer is admin work on the control-plane host, not fleet provisioning. It exists because that host is the one machine every control plane has and the server itself runs on, a headless box you might reach only through the browser.

For a node, installing an agent CLI means installing it on that machine: the plane's installer runs on its own host and nothing else. Use the same commands above over SSH, package the CLIs into your node images, or have whoever owns that machine do it the way they prefer. Then press Re-check on the node's Harnesses card (owner or edit access) and its rows update to what the machine has. Detection answers per machine; the picker keeps offering each agent only where its binary was found.

See also

• The Plugin Registry: installing plugins, the other and more privileged act
• Add a Node: enrolling the machines these CLIs need to reach
• Audit Log: where installs and refusals are recorded
• Security model: the trust posture these limits sit inside; the full accounting is in docs/security.md §11.10 on GitHub

Edit on GitHub