Start a project agent from a control session

Added in v0.213.1 A control session watches your projects but works in none of them. orboto agent start is how it hands work to a project: it starts a supervised project agent in that project's checkout on the same machine, with no terminal to open. The same command works from any shell.

orboto agent start ACME --ticket ACME-1234 --yolo               # Claude Code worker on the ACME checkout, its start prompt is the ticket
orboto agent start ~/src/my-project --harness codex --prompt "Review the open PRs"
orboto agent list                                              # the starts of this machine with their state
orboto agent stop 3f9a1c2e                                     # session id, live session id, start id or pid

Added in v0.215.0 The same start request can come from a chat: /orboto start ACME-12 in Slack, Microsoft Teams or Discord hands it to the project's control session, which runs orboto agent start on its own machine. See the chat bot.

Start

orboto agent start <KEY|checkout path> [--harness claude|codex|gemini|kimi] [--role worker] [--prompt "..."|--ticket KEY] [--yolo] [--profile <name>] [--json]

The checkout registry

orboto connect records the checkout it wires, and every orboto claude start that resolves a project records it too, in ~/.orboto/checkouts.json. A checkout recorded by orboto connect is preferred over one recorded by a start. The registry holds the 200 newest entries. A key that has no registered checkout on this machine is refused with the command to run once in the checkout: orboto connect --project KEY.

What happens

The harness starts under its own launcher (orboto claude --role worker --scope-projects KEY, or orboto codex, gemini, kimi) as a detached process: it has its own session, no controlling terminal, and its output goes to ~/.orboto/agents/<start id>.log. Its supervisor runs the harness in a terminal of its own that nobody watches locally, the same supervisor a terminal start uses. The session registers like any other, so it shows up under Admin -> Agents -> Live with its terminal and console, and an operator can take it over there. This is also where Claude Code's development-channel confirmation is answered when the channel plugin is not installed in the checkout; the start prints a note when that applies.

Every start gets an instance token of its own, so it never lands on the row of a session that runs in the same checkout.

A successful start prints:

orboto agent: claude started in <checkout> (start <start id>, pid <pid>, <state>)
  session  <session id>
  live     <live URL>
  starter  <starter session id> - its ticket-ready and completion mail is copied there
  stop     orboto agent stop <session id>

Refusals

These stop with exit code 2 and the reason, before anything runs:

• the checkout is not wired: it resolves no project, no checkout of the key is registered on this machine, or a Claude Code checkout has neither the CLI-form orboto server entry nor the channel plugin (orboto connect --project KEY in that checkout fixes it);
• the harness is not installed on this machine;
• the login, or the profile --profile names, cannot see the project;
• --ticket names a ticket of another project than the checkout's;
• --prompt together with --ticket;
• any prompt (--prompt or --ticket) for kimi: its prompt mode answers once and exits, so a detached kimi start takes none;
• an unknown --harness or --role.

Gemini CLI gets the prompt as --prompt-interactive, because it runs a plain positional prompt one-shot when it detects no terminal. A restart of the Gemini session does not send the prompt again.

A start that ends right away, or that has not declared its session and registered its live session within 60 seconds, exits with code 1 and prints the end of its log. In the timeout case the supervisor still runs; the message names orboto agent stop <start id>.

The starter gets the results back

When the shell that runs orboto agent start belongs to an orboto session, such as the control session, the started session names it as its starter. The instance records the starter only when it is an open session of the same account; a start under another account's --profile records none, and the refusal is written to the audit log.

With a starter recorded:

• the starter receives a copy of every complete message the started session sends, addressed to the starter's own session. The starter's account has to be a member of the message's project.
• the starter receives an info copy of every ticket-ready message addressed to the started session, as long as the starter may read the ticket.

A shell outside any orboto session records no starter, and the output says starter none. The start never passes on the starter's own session identity, project key or role to the started session.

List and stop

orboto agent list [--json] [--prune]
orboto agent stop <id> [--wait 30s]

orboto agent list shows what this machine started, with its state, harness, role, scope, session and live session. An ended start stays listed until you run it with --prune, which forgets ended starts older than seven days together with their logs. A supervisor that runs without a record on this machine is counted in a closing line, and orboto claude --sessions lists it.

orboto agent stop takes the session id, the live session id, the start id or the pid. It asks the supervisor to stop the harness the same way a restart does (Ctrl-C through its terminal, then terminate, then kill), ends the live session and exits. It waits 30 seconds by default for that (--wait) and exits with code 1 if the supervisor is still running then. An id that matches no start, or more than one, is refused with exit code 2.

Good to know

• Starting and stopping are CLI only: nothing in the REST API or the MCP tools starts a process on a machine. An agent that only has MCP runs the command in its shell.
• The detached start is tested on Linux and macOS. On Windows it builds, but nothing has run it there; treat it as untested.
• The role grants nothing by itself: the started agent works with the permissions of its login.

See also Sessions, scope and the wake ledger, Launchers and the uniform flags and Run an agent fleet.