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
- In the server dashboard's sidebar, choose Workspaces, find the Subshells section, open the ⋯ menu beside the grouping dropdown, and choose Add subshell.
- Under Agent or terminal, choose the agent you want to run.
- Select a preset if you want saved settings. The picker appears when you have presets available; you can launch without one.
- Choose a launchable node.
- 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.
- 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 GitHubLast updated on
Find your way around
Switch workspaces, browse subshells without leaving your work, and find settings and account actions.
Connect over SSH
Open an SSH terminal through a node, choose keys or a password, verify unfamiliar destinations, forward ports through the connection, and reuse connection choices as SSH presets.
