Subshell Docs

Launch a subshell

Launch an agent or shell in a new subshell.

Before you start

Sign in and choose a machine where you have launch access. The node must be online, outside maintenance, and have the required agent CLI installed. An administrator can also disable server-host launches or place the instance in lockdown.

Launch

  1. In the server dashboard's sidebar, choose Workspaces, find the Subshells section, open the ⋯ menu beside the grouping dropdown, and choose Add subshell.
  2. Under Agent or terminal, choose the agent you want to run.
  3. Select a preset if you want saved settings. The picker appears when you have presets available; you can launch without one.
  4. Choose a launchable node.
  5. Choose an existing working directory on that node. Select the field to browse folders, or type an absolute path. Selecting a folder updates the field and opens that folder; use .. to go up one level. Recent and Favorites provide shortcuts, and the star beside a folder adds or removes a favorite. Scroll to load more folders on the server. If a node’s listing reaches its limit, a notice explains that some folders may be missing; you can still type the path directly.
  6. Add task text if needed, then launch.

The form can prefill values from your last session or from a preset. Review those values, especially after choosing a different node: working directories belong to a particular machine.

A preset's defaults are hints in the human launch form and remain editable. Agents launching another agent over MCP need a saved preset ID. They can open a plain terminal without a preset.

Connect to another machine

Choose SSH terminal in the same dialog to connect from a node to an SSH destination. The destination doesn’t need Subshell installed. Follow Connect over SSH for the connection form, authentication choices, and destination verification.

Check the result

The new subshell opens as a workspace tab. With no workspace on screen, it joins your last available workspace or creates one if none exists.

Open the terminal and confirm that the CLI reaches its normal prompt. Complete provider authentication on the execution machine if the agent needs it.

If launch fails, check Agent and launch errors before repeating the request.

Next steps

Create Presets for repeatable launches, or arrange sessions in Workspaces.

Edit on GitHub

Last updated on

On this page