muster

Overview Schema Source Related Servers Discussions Admin

run

Launch instructed Codex, Claude, or OpenCode agents as sessions or one-shot tasks, with sandbox, permission, model, project, and timeout controls.

Instructions

Launch an instructed agent. Sessions return only when reachable; tasks return a non-messageable run handle.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cwd`	No
`mcp`	No	Configured MCP server names. Omit for session defaults; [] disables all. Tasks have no defaults.
`ttl`	No	Stop this tmux session the given duration after launch regardless of activity, as 90s/30m/4h, or 'off'. Off by default.
`args`	No
`host`	No
`kind`	No		session
`open`	No	Open the tmux session in a terminal viewer (macOS only).
`level`	No	A spelling of a legal permissions/sandbox pair: read is deny + read-only, work is auto + workspace-write, open is bypass + full-access. Naming a level and either flag is an error.
`model`	No	Model for the launch. A bare model id for claude and codex; PROVIDER/MODEL for opencode, where it overrides the configured [opencode] model. Recorded on the run and reported by `list`.
`title`	No	Terminal title for this tmux session, shown by any terminal attached to it. Defaults to the session's name and runtime once it is reachable; the agent's own title is shown instead only with [session] title_from_agent. Control characters are stripped and it is capped at 100 characters. Refused for tasks and for pty or macos-terminal hosts.
`plugin`	No	Configured OpenCode plugin names. Omit for session defaults; [] disables all. OpenCode only.
`prompt`	Yes
`options`	No	Muster-side launch options. auto-approve-path records the launch directory as trusted in the profile the agent will use, so its one-time dialog does not block the launch; refused for a runtime with no trust gate, and refused if the directory ships hooks or MCP servers. accept-bypass-warning accepts Claude's one-time Bypass Permissions warning for a bypass launch (level open); refused for other runtimes and without bypass permissions. Not expressible remotely.
`project`	No	A project named in config.toml, used instead of cwd. Naming both is an error.
`runtime`	Yes
`sandbox`	No	Defaults to config (read-only). Full access requires config authorization.
`identity`	No	A named identity created by `muster setup-identity`; the agent runs as that account instead of inheriting the ambient environment. A non-local requester is bounded by its profile's identities.
`terminal`	No	Viewer app; requires open. Auto uses Terminal.app.
`requestKey`	No	Caller-owned identity for this launch. Repeating it returns the launch it already produced instead of starting another; repeating it with different parameters is refused.
`idleTimeout`	No	Stop this tmux session after the given inactivity, as 90s/30m/4h, or 'off'. Off by default. Refused for tasks and for pty or macos-terminal hosts, which do not outlive their parent.
`permissions`	No	Defaults to config (deny). Auto requires workspace-write; bypass requires authorized full-access.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.2.0Oct 2, 2026

changedInput schema / properties / idleTimeout / description

Previous value: -"Stop this tmux session after the given inactivity, as 90s/30m/4h, or 'off'. Defaults to 30m. Refused for tasks and for pty or macos-terminal hosts, which do not outlive their parent."New value: +"Stop this tmux session after the given inactivity, as 90s/30m/4h, or 'off'. Off by default. Refused for tasks and for pty or macos-terminal hosts, which do not outlive their parent."

addedInput schema / properties / options

Added value: +{
+  "description": "Muster-side launch options. auto-approve-path records the launch directory as trusted in the profile the agent will use, so its one-time dialog does not block the launch; refused for a runtime with no trust gate, and refused if the directory ships hooks or MCP servers. accept-bypass-warning accepts Claude's one-time Bypass Permissions warning for a bypass launch (level open); refused for other runtimes and without bypass permissions. Not expressible remotely.",
+  "items": {
+    "enum": [
+      "auto-approve-path",
+      "accept-bypass-warning"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / title

Added value: +{
+  "description": "Terminal title for this tmux session, shown by any terminal attached to it. Defaults to the session's name and runtime once it is reachable; the agent's own title is shown instead only with [session] title_from_agent. Control characters are stripped and it is capped at 100 characters. Refused for tasks and for pty or macos-terminal hosts.",
+  "type": "string"
+}

Changed2 schema fields changedv0.9.1Sep 24, 2026

addedInput schema / properties / idleTimeout

Added value: +{
+  "description": "Stop this tmux session after the given inactivity, as 90s/30m/4h, or 'off'. Defaults to 30m. Refused for tasks and for pty or macos-terminal hosts, which do not outlive their parent.",
+  "type": "string"
+}

addedInput schema / properties / ttl

Added value: +{
+  "description": "Stop this tmux session the given duration after launch regardless of activity, as 90s/30m/4h, or 'off'. Off by default.",
+  "type": "string"
+}

Changed1 schema field changedv0.7.21Sep 24, 2026

changedInput schema / properties / model / description

Previous value: -"PROVIDER/MODEL, overriding the configured [opencode] model. OpenCode only."New value: +"Model for the launch. A bare model id for claude and codex; PROVIDER/MODEL for opencode, where it overrides the configured [opencode] model. Recorded on the run and reported by `list`."

Changed6 schema fields changedv0.7.14Sep 23, 2026

addedInput schema / properties / identity

Added value: +{
+  "description": "A named identity created by `muster setup-identity`; the agent runs as that account instead of inheriting the ambient environment. A non-local requester is bounded by its profile's identities.",
+  "pattern": "^[a-zA-Z0-9_-]+$",
+  "type": "string"
+}

addedInput schema / properties / level

Added value: +{
+  "description": "A spelling of a legal permissions/sandbox pair: read is deny + read-only, work is auto + workspace-write, open is bypass + full-access. Naming a level and either flag is an error.",
+  "enum": [
+    "read",
+    "work",
+    "open"
+  ],
+  "type": "string"
+}

addedInput schema / properties / model

Added value: +{
+  "description": "PROVIDER/MODEL, overriding the configured [opencode] model. OpenCode only.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / plugin

Added value: +{
+  "description": "Configured OpenCode plugin names. Omit for session defaults; [] disables all. OpenCode only.",
+  "items": {
+    "pattern": "^[a-zA-Z0-9_-]+$",
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / project

Added value: +{
+  "description": "A project named in config.toml, used instead of cwd. Naming both is an error.",
+  "pattern": "^[a-zA-Z0-9_-]+$",
+  "type": "string"
+}

addedInput schema / properties / requestKey

Added value: +{
+  "description": "Caller-owned identity for this launch. Repeating it returns the launch it already produced instead of starting another; repeating it with different parameters is refused.",
+  "maxLength": 200,
+  "minLength": 1,
+  "type": "string"
+}

Changed4 schema fields changedv0.7.8Sep 22, 2026

addedInput schema / properties / mcp

Added value: +{
+  "description": "Configured MCP server names. Omit for session defaults; [] disables all. Tasks have no defaults.",
+  "items": {
+    "pattern": "^[a-zA-Z0-9_-]+$",
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / open

Added value: +{
+  "description": "Open the tmux session in a terminal viewer (macOS only).",
+  "type": "boolean"
+}

changedInput schema / properties / runtime / enum

Previous value: -[
-  "codex",
-  "claude"
-]New value: +[
+  "codex",
+  "claude",
+  "opencode"
+]

addedInput schema / properties / terminal

Added value: +{
+  "description": "Viewer app; requires open. Auto uses Terminal.app.",
+  "enum": [
+    "auto",
+    "terminal",
+    "iterm2",
+    "ghostty"
+  ],
+  "type": "string"
+}

First observedv0.3.0Sep 19, 2026

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose one important trait: sessions only return when reachable and tasks yield a non-messageable handle. That is genuinely useful blocking/return semantics, but it says nothing about permissions, sandbox bypass, or refusal conditions that dominate this tool's risk profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the action and followed by the mode-dependent outcome. Every sentence earns its place, though the brevity is stark against a 21-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-parameter launch tool with no annotations and no output schema, the description is far too thin. It omits auth/prerequisite context, safety-relevant launch semantics, and any return-structure detail beyond the single task-handle note.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 71%, so the schema documents most parameters in detail. The description adds meaning only for the session/task outcome, not for any named parameter, so it neither compensates heavily nor repeats the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Launch an instructed agent") and clarifies the two operating modes it produces. It is clearly the launching tool versus siblings like list/output/stop, though it does not explicitly name or contrast against them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not guidance for the 21 parameters. The session-vs-task return distinction implies how the kind choice behaves, but prerequisites and exclusions are left to the schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

run

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools