Design a custom agent

A custom agent is for work no stock template covers. You describe the job in plain operational terms; the Charter Builder turns that into a Charter, a permission manifest, and a dry-run task. You never write a prompt — custom prompt editing is an advanced option that opens only after the operational Charter is complete, and the Charter stays the control plane.

Start with operational questions

Begin from the agents surface (Design a custom agent) or from the CLI/MCP. The wizard asks four questions:

• What work should this seat own?
• What does success look like? (these become Signals)
• What must it never do alone? (these become approval and escalation boundaries)
• Who stewards it? (the accountable human)

Let the Charter Builder assemble the job

From your answers, the Charter Builder drafts responsibilities, decision authority, Signals, handoffs, and escalation rules. Review and edit every clause. Keep the autonomous scope tight at first; you can grant more authority later once dry runs and evidence justify it.

Choose a lane and a trigger

Pick where the agent runs and what starts it. Both lead with a safe default, so a non-technical operator never has to write a raw schedule or reason about an internal lane name.

A custom agent runs on one of three lanes:

• Cloud agent (recommended) — the ROST-managed runtime using the tenant model key. It needs no local machine, pairing, or token, so it is the default if you are unsure.
• External MCP agent — a Claude Code, Codex, or Cursor agent that connects to ROST as the seat.
• Local Runner — scheduled local execution through a paired Runner.

Then choose one of three named triggers:

• On demand (default) — runs only when you or a teammate start it. No schedule.
• Scheduled — runs on a recurring cadence you pick (every weekday morning, every morning, weekly, hourly). No cron to write.
• Event — runs in response to work routed to it, like a sync or a mention, rather than on a clock.

Open Advanced for the explicit lane select and a raw cron expression when you need a custom cadence. The same schedule presets appear on the agent's seat page after go-live (Agent operations → Run schedule).

Configure tools and credentials

Propose tools, then connect or decline each one. Declining updates the permission manifest and the dry-run task so the agent still operates safely or clearly explains the blocker. Credentials are entered through write-only credential ingress and stored as vault references; raw secrets never appear in prompts, logs, or tool arguments. When a connected tool needs a credential, you stage a request with a short credential *name* — a label only. The name and its scope are validated to reject pasted secret material, so a key can never reach the append-only event log; you provide the secret itself later through the vault-backed ingress flow.

From CLI or MCP

The same path is command-backed:

1. agent_setup.start / rost_start_agent_setup with mode custom returns a setup_id. 2. Iterate with agent_setup.get and agent_setup.update (parent, Steward, lane, schedule, and the operational answers). 3. agent.create_custom / rost_create_custom_agent seeds a custom agent and a draft Charter from the operational answers only. 4. agent.configure_tools / rost_configure_agent_tools records connect/decline decisions and credential-ingress requests (vault refs only). 5. agent.run_dry_run / rost_run_agent_dry_run rehearses the task after the manifest is signed.

Dry run and go-live

The dry run is a real sandbox rehearsal, not a stamp. It executes a mock-provider run derived from the Charter — the agent works against sandbox data only and is expected to escalate where the Charter's must-escalate clause requires it. The same rehearsal works on all three lanes: cloud, external MCP, and local Runner. External MCP dry runs require an active seat-scoped MCP token; Runner dry runs require a paired Runner. Missing substrate returns a typed precondition error, not a generic failure. The recorded run keeps the agent's actual lane, so the evidence you review matches the lane you selected. The result is earned: a run that escalates the must-escalate boundary passes; a run that acts on that boundary instead of escalating fails. A failed dry run keeps the draft and shows the reason so you can edit and rerun. The rehearsal returns a transcript — the steps the agent took and the escalation it raised — shown step by step in the builder and printed by the CLI, so you can see the governance model working before anything goes live. When the dry run passes, a human promotes the agent live. The dry run rehearses the specific model tier you chose, so once it passes the model is locked — changing the model requires re-running the dry run on the new model before go-live.

When to stop for confirmation

agent.create_custom, charter.sign_manifest, staffing.assign_user, and agent.go_live are human_required; agent.configure_tools and credential.ingress are credential_flow (both gate through the vault-backed credential path with human approval; agent.configure_tools stages the request and only credential.ingress takes the raw secret, as a vault reference). agent.run_dry_run is ungated by human approval but requires a signed manifest first — a dry run before charter.sign_manifest returns a clean COMMAND_PRECONDITION_FAILED pointing at charter.sign_manifest. The go-live after a passed dry run is human_required. An agent may draft, configure (with vault refs), and dry-run; only a human approves the Charter, manifest, credentials, and go-live. A seat token can never create or approve its own setup. See the confirmations guide.