Agent, fleet, batch and graph commands

Give a coding agent a task in a sandbox, attach your terminal to its own interface, write agent profiles, run batches and fleets, serve a sandbox to an MCP client and run agent graphs.

tangle agent prompt my-box "Fix the failing test" --stream
tangle agent prompt my-box "Start on the issue" --interactive --harness codex
tangle agent profile create --name critic --harness codex
tangle fleet create --count 4

--harness picks the coding agent for one run. The flag table under tangle agent prompt lists the names it accepts; GET /v1/backends lists every coding agent the service offers. Interactive mode explains --interactive: what you see, the keys, and how to detach and reattach.

Commands on this page

Prompt a coding agent

tangle agent prompt

Send a single prompt to the agent. With one arg it’s the prompt and the box comes from tangle use / --box / TANGLE_SANDBOX; with two it’s <id> <message>.

Sends one prompt to the sandbox’s agent. Default: waits and prints the response with duration and token counts. --stream prints text as it arrives. --interactive starts the coding agent’s native terminal UI in the sandbox and attaches your terminal to it.

tangle agent prompt <idOrMessage> [message] [options]

Request: POST /v1/sandboxes/{id}/runtime/agents/run/stream

tangle agent prompt my-box "Summarize the README" --stream

• One positional is the prompt and the sandbox comes from --box, TANGLE_SANDBOX or tangle use; two positionals are <id> <message>.
• --profile here is an AgentProfile source (path, https URL or github:owner/repo/path@ref), not a credential profile.
• --timeout defaults to 300000 ms.
• --harness picks the coding agent for this run; the help lists claude-code, codex, kimi-code, opencode, pi, amp, hermes.
• --connection grants Hub connections as MCP tools: <connection>:<cap1>,<cap2>, <connection>:* or :; --allow-writes pre-approves write actions of each named connection and refuses the : wildcard.
• A non-successful result exits 1 with guidance: blocked_on_approval prints tangle hub approvals approve <id>; awaiting_question suggests re-running with --interactive.
• --json (blocking) prints the SDK prompt result; --json --stream prints one final document with the outcome, response, tokenUsage and durationMs.
• --interactive --json prints {state, sessionId, harness, streamUrl?, webUrl} and does not attach.
• Resumes a stopped sandbox first and waits up to 120000 ms for it to run.

Agent profiles

tangle agent profile create

Create a profile, interactively (a wizard), or fully via flags.

Creates an AgentProfile JSON file from flags, or through a prompt wizard when --name is omitted on a terminal.

tangle agent profile create [output] [options]

tangle agent profile create --name critic --harness codex --json

• Writes ./agent-profile.json unless an [output] path is given; --json prints the profile instead of writing it.
• Without a terminal, --name is required.

tangle agent profile show

Load and print a profile (local path, https URL, or github:owner/repo/path[@ref]).

Loads a profile from a path, https URL or github: ref and prints it as JSON.

tangle agent profile show <source>

tangle agent profile show ./agent-profile.json

• Always prints JSON, including errors, even without --json.

tangle agent profile validate

Validate a profile against the canonical AgentProfile schema.

tangle agent profile validate <source>

tangle agent profile validate ~/profile.json --json

• Invalid profiles exit 65 with code PROFILE_INVALID before any authentication.
• --json prints {ok:true, name}.

Framework snippets

tangle agent connect

Print a copy-paste SDK integration snippet for one of: anthropic, openai, vercel-ai, mastra, mcp-local, claude-desktop, cursor, zed (to stream a local agent’s telemetry to Intelligence, see ‘tangle connect’).

Prints a ready-to-paste integration snippet for anthropic, openai, vercel-ai, mastra, mcp-local, claude-desktop, cursor or zed; makes no network call.

tangle agent connect <framework> [options]

• Unknown framework exits 2, not the usage code 64.
• -i here means --sandbox (the id embedded in the snippet), unlike tangle ssh -i.

Agent backend in a sandbox

tangle backend status

Get backend agent status.

Shows the backend agent’s status.

tangle backend status <sandboxId-or-name>

Request: GET /v1/sandboxes/{id}/runtime/backend

tangle backend status my-box

tangle backend configure

Update backend configuration.

Updates the backend’s model.

tangle backend configure <sandboxId-or-name> [options]

Request: POST /v1/sandboxes/{id}/runtime/backend/configure

tangle backend configure my-box

• With no --model it sends an empty configuration.
• --json prints the configuration that was sent.

tangle backend mcp-status

Get status of MCP servers.

Shows the status of the backend’s MCP servers.

tangle backend mcp-status <sandboxId-or-name>

Request: GET /v1/sandboxes/{id}/runtime/backend/mcp

tangle backend restart

Restart the backend agent.

Restarts the backend agent.

tangle backend restart <sandboxId-or-name>

Request: POST /v1/sandboxes/{id}/runtime/backend/restart

tangle backend restart my-box

• Prints no JSON document.

Batches

tangle batch run

Execute a batch of tasks. Provide tasks via --tasks <file.json> and/or repeated --task id=message flags.

Runs a batch of tasks against one or more named backends and prints totals and per-task results.

tangle batch run [options]

Request: POST /v1/sandboxes/batch/run

tangle batch run --request ~/request.json --json

• Without --request, at least one --backend <id=type> is required; --model applies only when exactly one backend is selected.
• --request takes a complete SDK batch request file and cannot be combined with inline task or backend flags.
• --stream prints task.started/retry/completed/failed lines as they arrive; with --json those lines go to stderr and the final document to stdout.
• Exits 1 when any task failed; Ctrl-C prints ‘Batch cancelled.’ and exits 130.

Fleets

tangle fleet create

Create a sandbox fleet.

Creates a fleet of worker sandboxes from flags or a --spec JSON file and prints its machines.

tangle fleet create [options]

Request: POST /v1/fleets

tangle fleet create --count 4

• --coordinator creates a coordinator plus workers.
• --json prints {fleetId, machines}.

tangle fleet list

List the machines of one fleet (fleet id is required).

tangle fleet list <fleet-id> [options]

tangle fleet get

Show one fleet’s manifest (server record).

Prints one fleet’s manifest.

tangle fleet get <fleet-id>

Request: GET /v1/fleets/{fleetId}/manifest

tangle fleet delete

Delete a fleet’s machine sandboxes and its record.

tangle fleet delete <fleet-id> [options]

Request: DELETE /v1/fleets/{fleetId}

• --json prints {success:true, fleetId}.

tangle fleet reap

TTL cleanup of all expired fleets (fleet-wide).

Deletes every expired fleet; --dry-run reports what would be removed.

tangle fleet reap [options]

Request: POST /v1/fleets/reap-expired

tangle fleet reconcile

Drop fleet records whose underlying sandboxes vanished.

Drops fleet records whose sandboxes no longer exist; --dry-run reports them.

tangle fleet reconcile [options]

Request: POST /v1/fleets/reconcile

tangle fleet workspace snapshot

Snapshot the fleet’s shared workspace.

Snapshots the fleet’s shared workspace.

tangle fleet workspace snapshot <fleet-id>

Request: POST /v1/fleets/{fleetId}/workspace/snapshots

tangle fleet workspace restore

Restore the fleet’s shared workspace from a snapshot.

tangle fleet workspace restore <fleet-id> <snapshot-id>

Request: POST /v1/fleets/{fleetId}/workspace/snapshots/{snapshotId}/restore

tangle fleet workspace reconcile

Re-mount the shared workspace on all fleet machines.

tangle fleet workspace reconcile <fleet-id>

Request: POST /v1/fleets/{fleetId}/workspace/reconcile

tangle fleet exec

Run a shell command across the fleet’s machines.

Runs one shell command on every machine of a fleet (or a --machine subset) and prints a result table plus each machine’s output.

tangle fleet exec <fleet-id> <command> [options]

• Exits 1 when any machine fails.

tangle fleet run

Create a fleet of agents, run one turn on every agent, print each result, then delete the fleet.

tangle fleet run [prompt] [options]

• --agents is required: a count, or a JSON file of agent specs; a count needs the [prompt] argument.
• --model forces the opencode backend for every agent.
• The fleet is deleted even when the run fails, unless --keep.
• Exits 1 when any agent did not complete; --json prints {fleetId, createMs, sandboxes, results, spend, deleted}.

tangle fleet cancel

Interrupt every agent of a fleet and cancel its child fleets; sandboxes keep running.

tangle fleet cancel <fleet-id>

• --json prints {fleetId, interrupted, children}.

tangle fleet capabilities

List fleet drivers and their supported features.

Lists fleet drivers and the features each supports.

tangle fleet capabilities

Request: GET /v1/fleets/capabilities

tangle fleet usage

Show fleet usage and reliability insights.

Shows a fleet’s usage and reliability insights.

tangle fleet usage <fleet-id>

Request: GET /v1/fleets/{fleetId}/usage

tangle fleet cost

Show the fleet’s cost estimate.

Shows a fleet’s cost estimate.

tangle fleet cost <fleet-id>

Request: GET /v1/fleets/{fleetId}/cost

tangle fleet token

Mint a scoped fleet bearer token (treated as a secret).

Mints a scoped bearer token for a fleet; treat the output as a secret.

tangle fleet token <fleet-id> [options]

Request: POST /v1/fleets/{fleetId}/token

• The --action help says the ‘prompt’ action grants nothing because fleet prompt dispatch was removed.

MCP server

tangle mcp serve

Run a local MCP server (stdio) backed by the given sandbox (ID or name). Pipe its stdio from an MCP client config to expose sandbox tools.

Runs a local MCP server on stdio backed by a sandbox, for MCP clients such as Claude Desktop, Cursor or Zed.

tangle mcp serve <id-or-name> [options]

tangle mcp serve my-box

• Requires @modelcontextprotocol/sdk installed separately; otherwise it fails with an install hint.
• Runs until stdin closes or SIGINT/SIGTERM.

Supervisor

tangle supervise

Run a budget-conserving supervisor that spawns isolated sandbox workers to deliver a task.

Runs a budget-limited supervisor that spawns isolated sandbox workers to deliver a task and reports measured tokens and cost.

tangle supervise <task> [options]

tangle supervise "Add input validation to POST /users" --harness opencode --max-workers 2

• The supervisor itself calls the Tangle router (TANGLE_ROUTER_URL overrides it) with your key.
• --model must name a provider, e.g. google/<model>.
• --harness accepts claude-code, opencode, codex, kimi-code, prime.

Agent graphs

tangle graph new

Design, validate and run one portable graph.

Designs, validates and runs one graph from a plain-language intent; --name saves it.

tangle graph new <intent> [options]

tangle graph new "Write and independently judge a haiku" --name haiku-review

tangle graph analyze

Analyze retained graph evidence through Braid.

Analyzes a retained graph run through the separately installed Braid CLI.

tangle graph analyze <run> [options]

tangle graph analyze <run-id> --profile ./profiles/reviewer.json

• Requires npm install --global @tangle-network/braid; BRAID_BIN selects the executable.
• --profile selects an analysis AgentProfile, not a credential profile.

tangle graph repair

Diagnose a failed local graph run; patch and resume it when the graph owns the fix.

Diagnoses a failed local graph run and, when the graph owns the fix, patches and resumes it.

tangle graph repair <run> [options]

tangle graph improve

Measure graph arms on js-issues by offline replay.

Measures graph variants (‘arms’) by offline replay on a dataset.

tangle graph improve <graph> [dataset] [options]

tangle graph improve ~/a.graph.yaml

tangle graph show

Draw a graph file: labelled nodes, routes, loops and stops.

Draws a graph file in the terminal; --open writes an offline HTML page and opens it in the browser.

tangle graph show <name-or-file> [options]

tangle graph inspect

Inspect a live or retained graph run.

tangle graph inspect <run>

tangle --json graph inspect <run-id>

tangle graph run

Run a saved graph over native subscriptions.

Runs a saved graph on the local coding agent subscriptions, or through cloud workflows with --cloud.

tangle graph run <name-or-file> [options]

tangle graph run haiku-review --dry-run --json

• Progress goes to stderr; --json prints the result or the error document on stdout.
• Gates ask on a terminal; without one, or with --json, pass --param gate.<id>=<choice>.
• On a terminal, a missing Tangle login opens browser login and a missing provider connection opens the provider’s browser authorization, then the run resumes.
• Ctrl-C stops the run with code RUN_STOPPED and exit 130.

Skill file

tangle skill path

Print the absolute path to the SKILL.md shipped with this CLI.

Prints the absolute path of the SKILL.md bundled with the installed CLI.

tangle skill path

Next

• Interactive mode
• Start a cloud agent
• Agent graphs