Subshell Docs

Set launch defaults

Prefill a preset's execution machine, project directory, and initial task.

Before you start

Create a preset and have launch access to the intended machine. Use an absolute working-directory path on that machine. The directory must exist and satisfy its directory rules when you launch.

Add defaults

  1. In the server dashboard sidebar, open Settings → Presets, open your preset's ⋯ menu, and choose Edit.
  2. Under Launch defaults, choose a node in Machine. The server host's node is named by your administrator and defaults to Server.
  3. Enter the project's absolute path in Working directory, such as /tmp/subshell-demo-project for the sample project.
  4. Under Add prompts, select Add prompt and choose saved instructions or Write your own....
  5. Add more prompts if needed. Use their up and down controls to set the order, and remove any you don't want.
  6. Select Save.
Launch defaults showing the Server machine, a project directory, Review changes prompt, and enabled agent-created launches.
The example combines a project location with review instructions. Its optional MCP switch allows agents to use the preset. Select the image to enlarge it.

For the review example, the task text is:

Review the uncommitted changes. Report correctness issues and missing tests
with file paths and line numbers. Do not modify files.

Prompt text guides the agent; it isn't a security boundary. Agent flags and permissions still govern what the process can do.

Save a virtual display choice

Enable Virtual display to include a screen when launching from this preset. Under Display provider, keep Node default or choose a specific provider. The list shows only providers the selected machine's operating system can run, and it follows the machine: choosing one that can't run what you'd saved clears the pick back to Node default rather than storing a launch the node will refuse. Saving the preset doesn't enable displays on its machine or start any processes. At launch, the chosen node must allow that provider and meet its requirements. See Web previews & screens.

The launch form copies this choice along with the other defaults. You can select another enabled provider or turn off Virtual display before starting. Once a subshell starts, it keeps its actual provider on restart even if you later change the preset or the node default.

Review before launching

The launch form fills in these defaults and lets you change them. A preset can name an agent and leave the machine open. If the form's default machine can't run that agent and there's another machine to choose, the form keeps the agent and leaves the machine unselected so you can choose one that has it. Switching nodes replaces the working directory with that node’s recent path or home. If the selected agent can’t run there, the form clears it and the preset selection, then asks you to choose another agent. Your prompt text stays in the form. Virtual display is turned off if the new node can’t provide it.

You can save a default for a machine that is temporarily offline. Launch still checks availability, maintenance, agent detection, permissions, and directory rules. Saving defaults doesn't bypass those checks.

Prompt text is copied when you select it. Editing the prompt library later doesn't update the preset's saved text. Remove and re-add a library prompt or stack to refresh the saved copy, then save the preset. See Build prompt stacks.

Allow agent-created helpers

On the same preset editor, turn on Enable agents to create subshells with this preset, then select Save. This requires a machine and working directory; an initial prompt is optional.

The switch permits MCP launches with this preset. It doesn't grant access to another account's node or bypass launch checks. See Use and manage presets and Coordinate agents.

Next steps

Follow Use and manage presets to launch the saved configuration.

Edit on GitHub

Last updated on

On this page