Subshell Docs

What is Subshell?

Subshell gives you a shared web interface for running CLI coding agents and terminal sessions on machines you own.

A subshell is a terminal session running an agent or a shell. You launch a subshell, choose where it runs, and interact with its terminal from a browser or Subshell Client. Subshell keeps the session available when you close the browser tab, so you can return to the same running process from another device.

Why use Subshell?

Subshell is self-hosted and open source. You run the server on your own infrastructure and control its accounts, configuration, and access to enrolled machines. The source code is public, so you can inspect how it works, contribute improvements, or modify it under its licenses. Server code is AGPL-3.0-only; the rest of the project is Apache-2.0. See Contribute to Subshell for licensing and contribution details.

Use Subshell to keep coding agents running beyond a single terminal window, work across machines, or manage several sessions together. Agent CLIs still use their own provider accounts; self-hosting Subshell doesn't make a cloud-based agent run locally.

What you want to doHow Subshell helps
Host the session dashboard yourselfRun the server on infrastructure you control and manage who can access it.
Inspect or adapt the softwareRead the public source, contribute improvements, or modify it under its licenses.
Check a task from another deviceOpen the server in a browser and reconnect to the running session.
Run an agent on a different machineEnroll that machine as a node and select it when launching a subshell.
Work with several agents or shellsKeep sessions in one dashboard and arrange them in workspaces.
Repeat a launch configurationSave agent settings and optional machine, directory, and prompt defaults in a preset.
Let someone inspect a sessionShare it with another account on the same instance, with view or edit access.
Let agents coordinate a taskConfigure Subshell MCP so agents can inspect sessions, exchange channel messages, and launch helpers from eligible presets.

Keep sessions in one place

Your workspace is the main working view. Use Subshells below the workspace members to browse sessions by machine or status without leaving that workspace. For a full tile or list view with recent output, choose Subshell dashboard from the ⋯ menu beside the grouping dropdown. You can run a plain shell with Terminal, or install a supported coding agent CLI on the execution machine.

Subshell dashboard listing Project shell and Test results in List view, with a New subshell button.
The dashboard brings your sessions into one view. This example shows two terminal sessions for a sample project. Select the image to enlarge it.

Subshell includes harnesses for Claude Code, Codex, OpenCode, Gemini CLI, Qwen Code, Cline, Open Interpreter, OpenHands, OpenClaw, Grok Build, Hermes Agent, pi, and Oh My Pi. You install and authenticate the agent CLI under the OS account where it runs. Subshell manages the session and provides access to it; the agent uses its own provider account and credentials.

Closing a browser tab disconnects your view. The session can keep running while its machine and process remain available. Stopping the machine or exiting the process affects the session, and the Close action deletes it and its captured history. See Session lifecycle.

A workspace brings related sessions together as panes. For example, you can keep a coding agent and a shell for checking its changes side by side, and the app opens back on the workspace you were last in. New sessions join as tabs, and you can drag tabs to create splits on desktop. On smaller touch screens, workspace panes appear as tabs. The sidebar shows only the active workspace’s subshells; its selector switches workspaces. See Find your way around.

Project workspace with a shell and test results side by side.
A project shell and its test results run in separate workspace panes. Select the image to enlarge it.

Presets save agent or SSH settings you want to reuse. Share them with teammates using view or edit access, or export and import a preset file to create a private copy on another server. Reusable Prompts keep reusable task text. Workspaces organize the sessions themselves.

Run on machines you choose

Subshell has three components:

  • The server is the control plane. It manages the instance, stores its database, and serves the web interface.
  • A node is a machine that runs agents and shells. The server's host can run sessions too; enroll additional nodes when you want to use other machines.
  • A client is your interface to the server, such as a browser or Subshell Client.

You can run the server on a machine that stays available, use your laptop as a node, and open the dashboard from another device. The agent runs on the selected node and uses that machine's working directory and OS account. Remote access requires a reachable server address; Networking covers LAN access, private networks, and HTTPS.

For most desktop installations, Subshell Server installs and manages the server, and Subshell Client bundles the node and its enrollment window. CLI installation suits headless machines. Downloads are available at subshell.sh.

Coordinate agents through MCP

Subshell's Model Context Protocol server gives configured agents tools to inspect sessions, send input, exchange encrypted channel messages, and create helpers from saved presets that allow agent launches.

This is useful when one agent needs to delegate a bounded task or ask another session for information. The workflow still needs instructions about scope, permissions, and cleanup. The agent that creates a helper is responsible for terminating or deleting it when the work is done. Start with MCP and agent communication.

Understand the trust boundary

Agents run real programs with their execution account's permissions. Subshell doesn't sandbox their filesystem access. Enrolling a node gives the trusted server the ability to launch programs under that node's account, and sharing a session exposes its terminal output to the recipients.

Read Security model before enrolling machines or sharing sensitive work.

Start using Subshell

Follow Get started to install the server and launch your first Terminal session. If you already have an instance, Install an agent CLI and Launch a subshell.

Edit on GitHub

Last updated on

On this page