CLI and MCP installation guide

Use the public CLI when a technical operator, Claude Code, Codex, Cursor, or another local agent needs to help set up and operate ROST. Use MCP when the local agent should call ROST tools directly from its own client.

The MCP server is remote and token-backed. There is no local MCP daemon to install. The CLI logs you in, mints a scoped MCP token, and prints the registration block for the deployed /mcp route.

AICOS MCP mode is deliberately seat-scoped. In Settings, the AICOS panel can create a token for the canonical AI Chief of Staff seat and then marks MCP selectable only while a non-revoked, unexpired AICOS seat token exists. Do not use a tenant-admin MCP token to staff or test AICOS; it should operate as its own governed seat, with the web panel remaining the readiness monitor and transcript surface.

MCP clients may also expose their own native browser, search, file, or shell tools. Those native client actions are outside ROST receipts, cost accounting, and audit. Treat them as ungoverned scratch work until the source is fetched or recorded through a ROST MCP tool such as web.fetch, web.search, browser.read, a work-log evidence call, or another governed command. Only the ROST tool call creates the permission receipt and evidence record.

Managed Runner turns use a generated ROST MCP configuration instead of the operator's local MCP/client config. Ordinary business-agent runner turns are MCP-only, run in a read-only sandbox, and do not receive local provider keys such as Exa or browser-provider credentials. Codex runner turns ignore user config/rules, run ephemerally, and disable native search, browser, and computer-use features; Forge developer profiles keep their separate local-code workspace behavior.

Credential families

There are two separate CLI credentials. Do not mix them: giving an implementation agent your personal session would let it act as you.

Human operator session

A human operator uses the ordinary Supabase sign-in flow. The CLI stores that session in the user slot (OS keychain or the owner-only file store with ROST_CLI_ALLOW_FILE_TOKEN_STORE=1).

npx @rosthq/cli@latest login            # browser-callback flow
npx @rosthq/cli@latest login --device   # device-code flow; a human approves in any browser

This session can run any command the operator is authorized to run. An interactive TTY still requires the operator to answer the complete Approve <command> (confirmation <id>)? [y/N] prompt before the CLI records a reviewed approval.

Implementation access (agent-led setup)

An external implementation agent does not use the operator session. Instead, the operator runs:

npx @rosthq/cli@latest implementation access start --source-client claude-code

This starts a bounded, run-bound bootstrap flow:

1. The CLI prints a workspace /auth/device URL and a short code. 2. A human owner opens the URL in a browser, matches the code, and approves the request. 3. The browser shows a distinct "Authorize an implementation attempt" disclosure: the agent receives a short-lived implementation credential, not the owner's account session. 4. The CLI receives an rost_impl_ bearer minted with a short (~55 minute) TTL and stores it in a separate CLI credential slot (implementation-bootstrap account / implementation-bootstrap.json), never in the user session slot. While the run is paused waiting on a human confirmation (setup or activation staged), each use of the bearer renews it toward an 8-hour hard ceiling, so a long human decision — a laptop sleeping mid-run — does not kill the credential.

The bearer can check progress, read orientation data, and stage human-gated drafts. It can also close its own run:

rost implementation access status    # show run/token state
rost implementation access complete  # close the run as completed
rost implementation access abandon   # close the run as abandoned

To register the same bearer with an MCP client, use:

rost implementation access install-mcp --client claude-code
rost implementation access install-mcp --client codex
rost implementation access install-mcp --client cursor

This installs the single rost_impl_ bearer directly. There is no mcp_token.create step and no second token.

Bounded bootstrap surface

The implementation bootstrap policy (implementation-bootstrap-policy) projects the explicit class map for the rost_impl_ principal. That surface is intentionally narrow:

• Vetted reads: onboarding.status, onboarding.resume, graph.get, charter.list, charter.get, compass.get_current, goal.list, agent.list_fleet, skill.list, skill.catalog, agent_template.list, system.health, runner.status (lets the agent tell a runner-lane run's "runner offline" apart from "agent broken" while a staged agent.run_now awaits approval; every other runner.* command stays denied).
• Human-confirmed drafts: seat.create_complete, agent.create_custom, agent.create_from_template, compass.set, compass.approve_version, onboarding.finish. Each stages a pending confirmation for a human owner to decide. seat.create_complete is the one atomic complete-Seat path described below; it does not make its optional agent live.
• Lifecycle close: implementation_access.status, implementation_access.complete, implementation_access.abandon.
• Outside the bounded principal: everything else stays outside this class map. The separate human-only floor also includes all four credential_flow commands (agent.configure_tools, credential.ingress, integration.connect_rest, and tenant.anthropic_key.save), the none-class decisions for escalations, onboarding path selection, task proposals, Signal readings, and error logs, confirmation.approve / confirmation.reject / confirmation.remint, confirmation.dismiss / confirmation.dismiss_stale, confirmation.activation_set.list, agent_grant_intervention.resume, and coach.draft_guide. Those commands stop before an owner-session retry in a headless invocation; an explicit interactive TTY remains the human path. The policy lives in packages/commands/src/implementation-bootstrap-policy.ts and is enforced by both the runtime guard and a CI drift test.

A bootstrap bearer is minted with a short (~55 minute) TTL and renewed while a human gate is waiting — every use of the bearer while a staged confirmation for the run is still pending extends expires_at toward an 8-hour hard ceiling (least(created_at + 8h, now + 2h), never past the ceiling and never backwards), so a run does not die during a long human decision. Renewal is bounded and conditional: it fires ONLY while a gate is pending, so an idle or unattended credential keeps the short default and the ceiling caps the total lifetime no matter how many renewals occur. rost implementation access status reports the remaining life (expires_in_seconds) and whether the run is gate_waiting. Once the bearer fully lapses (no gate was waiting, or the 8-hour ceiling was reached), there is no resume or refresh: the ONLY recovery is a brand-new implementation access start, which mints an entirely new, unrelated run. implementation_access.complete/.abandon's run_id is always the run THAT call closed — the one bound to the credential presented on that specific request — never a stand-in for an earlier run in the same overall onboarding session. If a credential expiry (for example, a host going to sleep mid-run) forced a fresh start partway through, the run that performed the earlier setup/rehearsal/activation steps is a DIFFERENT id from the one complete reports. Both close responses also carry reconciled_stale_run_ids: the ids of any OTHER runs for the same tenant whose bearer had already lapsed, reconciled to expired as a side effect of this close. It is normally empty; it is populated whenever this tenant has a run like that sitting around — most often the predecessor from a mid-session restart, but equally an earlier implementation-bootstrap attempt that was simply never explicitly closed.

Read that field against already_closed, which is returned alongside it. An empty reconciled_stale_run_ids means "swept, nothing was stale" only when already_closed is false. When already_closed is true the call was an idempotent no-op — it closed nothing, so it reconciled nothing, and the empty array means "did not look" rather than "this tenant has no stale runs". Reconciliation is also a side effect of closing, not a scheduled sweep: a tenant that never closes a run, and a run that was opened by a device approval that was never polled (so no bearer was ever minted), are both outside what this reconciles. #### How the CLI reaches that surface

With an implementation credential present, the CLI runs every classified command over that credential — on the generic rost command <id> --json '<body>' path and on the ergonomic verbs that resolve to a classified command: rost graph show, rost seat list, rost agent list-fleet, rost agent templates, rost goal list, rost system health, rost skills list, rost skills catalog, rost charter list, and rost charter get. Every other vetted read in the class map — including the ones with no ergonomic verb — is reachable as rost command <id> --json '<body>', and this precedence remains true when a user session coexists.

A command outside the class map is never emitted through the implementation client. A human-decision command in that family stops before an owner retry in a headless session; an explicit interactive TTY remains the existing human signal for the owner path. An expired, unreadable, unauthenticated, or refused implementation credential is terminal for the invocation and is never silently replayed as the owner. When implementation_access.complete or .abandon succeeds, the CLI clears the bearer and writes a local closed-run tombstone (implementation-bootstrap-closed.json, no secrets) so a later headless process can tell a completed or abandoned run apart from an owner who never started one; bootstrap-classified commands then refuse owner fallthrough until a new implementation access start.

Precedence. A usable implementation credential wins for every classified command, including general verbs and the composite onboarding wrappers, because the run is the bounded acting principal. It also decides the commands it is NOT entitled to run: while a run is live, a headless invocation of a deny-class command is refused outright, naming the command and the missing implementation route, instead of quietly executing under a co-resident owner session (DER-3255). The bounded credential is never sent for such a command either — both principals stop. An explicit interactive terminal is still the owner's deliberate path for those commands, and an absent credential leaves the owner-session path available unless a closed-run tombstone is present, in which case headless bootstrap-classified commands refuse instead of falling through to a co-resident owner session. Expiry, local-store errors, authentication failures, and policy refusals stop the invocation instead of falling through to the owner.

Some verbs that look like reads are not. A Markdown-rendering show verb resolves to a *.show_markdown command the policy denies, even though the same underlying data is inside the surface — read those through the vetted list/get verbs named in the allowlist above instead. Likewise rost agent fleet-digest (agent.fleet_digest) is denied; the vetted fleet read is rost agent list-fleet.

Staging behaves the same over either credential: a stage-class command exits 0 and prints the pending confirmation id and approval URL. The bootstrap principal never follows that with confirmation.approve — including under --yes — because a human decides (confirmation.approve is denied to it).

Full Operator device exchange

A Full Operator installation (a specific Codex, Claude Code, or comparable device identity) is a fourth ROST principal — distinct from a human operator session, a seat-scoped MCP token, and the implementation-bootstrap principal above. It never signs in as a person and is never coerced into a user session or an agent seat occupancy. It acts under a standing authorization a human owner deliberately established, and every action it takes is attributed to *the operator*, authorized by that human — never to the human directly.

> Current availability — no Full Operator session can be issued in the deployed Google-only sign-in configuration. Issuance requires a provider-backed, recent credential-authentication proof. The approval gate accepts only recent password, otp, or totp AMR evidence; the configured Google OAuth flow cannot provide that proof, and /auth/operator-reauth intentionally stops instead of treating account selection or a new OAuth callback as reauthentication. Do not start or poll this exchange expecting a session today. Use the ordinary human or implementation-bootstrap flows as appropriate. The protocol below becomes available only after a provider-backed fresh-authentication contract is configured.

When that prerequisite is available, the exchange uses two separate possession checks: an installation key binds the resulting session to the machine that started it, and a one-time poll secret keeps a copied device code from making the server perform unbounded signature work or consuming the legitimate installation's shared poll interval. Neither is a reusable user credential.

1. The operator client generates an ed25519 keypair for the installation and starts the exchange with purpose: "operator_grant", its own source_client label, and an installation_fingerprint_hash — the sha256 hex digest of the raw 32-byte public key (never the private key or any secret material — the CLI's secrets-never-travel rule above applies here too). The start response returns a challenge_nonce and a one-time operator_poll_secret. The client retains both; the service persists only their safe correlation values (the nonce and a SHA-256 hash of the poll secret), never the plaintext secret. 2. A human owner opens the printed /auth/device URL, matches the code, and approves. The browser shows a distinct "Authorize an operator" disclosure naming the requesting client and the company, and states plainly that this is an external operator installation, not a ROST agent. 3. The client polls with purpose: "operator_grant", its device_code, the exact lowercase-hex installation_fingerprint_hash sent at start, and the one-time operator_poll_secret, plus a possession proof: installation_public_key (the raw ed25519 public key, base64url, no padding) and challenge_signature (an ed25519 signature over the exact ASCII bytes of the challenge_nonce string from step 1, base64url-encoded, no padding, 64 raw signature bytes). All five values are required. The service requires both opaque-code hashes in its lookup before it locks a device row, decodes a key, verifies Ed25519, or writes a proof-work limiter hit. It then independently re-derives the fingerprint hash from the presented public key and rejects the poll unless it matches the value captured at start — presenting either a fingerprint hash or poll secret alone is not authentication; a valid signature over the exact nonce is still required. Proof work is durably limited by trusted caller partition and poll-secret hash, with a global cap; it never advances the device row's shared last_polled_at on a bad proof. Only the first successful poll mints a session bearer — prefix rost_operator_, a 15-minute TTL — and returns it exactly once. A copied code without its matching poll secret, a mismatched fingerprint, or a missing/invalid proof gets nothing without consuming the legitimate exchange.

When provider-backed issuance becomes available, there is still no revocation surface for an established Full Operator authorization — no route, command, or Settings action calls it. The tenant issuance setting and the operator issuance kill switch block future approvals and future session issuance; the poll re-validates the authorization and the installation as still active, inside the same transaction that mints the session, so a status change or a kill-switch flip that lands before the first poll blocks issuance rather than racing it. Neither can invalidate a session that has already been minted; that session runs out its own 15-minute TTL.

The protocol's permitted scope is deliberately minimal once issuance is available. Under ADR-0025, every command carries exactly one Full Operator classification, and an operator session may only call a command classified operator:

• Confirmation-free reads and status commands.
• Two input-predicated goal.* boundary commands: goal.bind_measurable (only an informs-only bind — any role other than absent or "informs" falls to a human) and goal.set_auto_status (only enabled: false — turning Signal-driven auto-status on falls to a human).

Everything else is denied, including any command the classification map has no explicit entry for — an unclassified or newly-added command defaults to blocked, never to operator authority by omission.

No mode, lane, or standing authorization — including a future, broader one — can let an operator, under any authorization:

• Handle or reveal raw secrets or credentials
• Mint a credential or token
• Act across tenants
• Capture or change owner or member access
• Destroy tenant or audit data
• Spend money
• Approve its own actions
• Expand its own authority

Operator eligibility is expected to grow beyond this minimal reads-plus-two-boundary-commands set, but only through a separate, security-reviewed, founder-approved-per-batch expansion (tracked as DER-2205) — U3 ships the minimal floor deliberately, not as a permanent ceiling.

Prerequisite: a human approver in a browser

A headless agent cannot complete setup unattended. Two things always require a human, so plan to announce the handoff rather than stall silently:

• Device-code approval at first login. rost login --device prints a code; a human must open the workspace URL in a browser, sign in with Google, match the code, and approve.
• Durable gated commands. Setting or approving a Charter, staffing a seat, taking an agent live, and minting or revoking an MCP token each require a human approval boundary (an agent never approves its own request — see the confirmations-guide). In a headless/agent session, or over MCP, the command surfaces the confirmation_id and an approveVia URL for a human and stops. When a logged-in human runs rost command <id> or rost mcp install from an interactive TTY, the official CLI renders the complete gate and asks Approve <command-id> (confirmation <id>)? [y/N]; only an explicit y or yes calls confirmation.approve with reviewed: true and prints the approved command output. TTY presence alone is never approval, and there is no headless token-mint bypass. See the confirmations-guide for which pauses an agent-led onboarding run hits under this bounded bootstrap surface, and the rule that produces them.

Treat these as blocking prerequisites: the agent prepares the request and waits for the human approver.

• Secrets never travel through the CLI. Raw-secret sinks (credential.ingress, tenant.anthropic_key.save) are refused on every CLI path — an ergonomic verb, --input, and rost command <id> --json all stop with guidance instead of accepting the secret, because a value in argv lands in shell history and process arguments before any redaction. Provide the secret through the vault-backed flow (web Settings or the integration connect flow); the CLI only ever carries the non-secret credential *name*, scope, and provider. Disabling tenant BYOK (tenant.anthropic_key.disable) never returns the old key; it revokes the active vault-backed credential only after managed Anthropic fallback is available.

Placeholder legend

Commands below use angle-bracket placeholders. The CLI prints the real, fully-resolved values at runtime — read them from the terminal, do not hand-construct them:

• <your-workspace-url> — your workspace origin. The CLI prints the full /auth/device and /mcp URLs in its output; copy them from the terminal rather than guessing the host.
• <tenant-slug-or-id> — a tenant identifier from rost tenants.
• <seat-id> — a seat id from rost command seat.create output or rost_get_responsibility_graph / rost command graph.get.
• <token-id> — an MCP token id printed by mcp install, or discoverable later via rost command mcp_token.list / rost_list_mcp_tokens.
• <confirmation-id> — shown in the CLI error or output for a gated command; see the confirmations-guide.

Before you start: create your account and company

A ROST account (the human identity) is created with Google sign-in — in the browser at /signup, or headlessly via rost login --device (a human approves the code in any browser). A company (tenant) can then be created either way:

• Browser: at /signup, name your company, then return to the CLI.
• Headless first company (no browser step): once logged in, run rost signup --company "<name>". If the account has no active company yet, this provisions the first company for your session and makes it active, so rost onboard status and every other tenant-scoped command work immediately. This is the recommended path for an autonomous agent setting up from scratch.
• Additional entitled company: from an existing active company session, run rost tenant create --company "<name>" [--json]. This creates a clean additional company only when the account has an active tenant.create.additional entitlement. A denied attempt returns a clean refusal and creates no tenant row.

If you run a tenant-scoped command before any company exists, the CLI tells you both first-company options. rost signup --company is not a second-company creation command: running it again returns the active company, names the company you requested, and says that no new company was created. The default output is human-readable; add --json only when an automation needs the raw command output. To inspect or switch among companies you can already access, use rost tenants and rost use <tenant-slug-or-id>.

Install the CLI

Run the published package with npx:

npx @rosthq/cli@latest --help
npx @rosthq/cli@latest login

Or install it globally:

npm i -g @rosthq/cli
rost login

The package requires Node 22 or newer. The binary name is rost. Check your version before installing — npx will still launch the package on Node 20 or 18, but the CLI rejects an older runtime:

node --version

If it prints anything below v22, upgrade Node first.

Headless agent login (device-code flow)

A coding agent (Codex, Claude Code, or any headless shell) signs in without a browser of its own: the agent prints a short code, and a human approves it in any browser. This is the recommended path for autonomous agents. Plain rost login (the browser-callback flow) stays the default for an interactive human at a keyboard.

rost login --device

How it works:

1. The CLI prints a verification URL (your workspace's /auth/device page) and a short code, then polls and waits:

   To sign in, open this URL in any browser and approve the code:
     https://<your-workspace-url>/auth/device

     Code: ABCD-EFGH

   Code also available via 'rost auth device status' if this terminal loses it.

   Waiting for approval…

The <your-workspace-url> shown here is a placeholder for this doc; the CLI prints your actual workspace origin. Read the URL and code from the terminal — do not hand-construct them. If a buffered or piped terminal (an agent's own | tail -40, a log capture that only flushes on exit) loses that one print, run rost auth device status from a second terminal or process on the SAME machine to reprint the URL, code, and remaining time — see "Recovering a lost code" below. 2. A human opens the URL, signs in with Google, confirms the code shown in the browser matches the one in the agent's terminal, and clicks Approve. 3. The CLI detects the approval, exchanges a one-time handoff for a session, and stores it in the OS keychain. rost whoami then shows the account, and tenant-scoped commands (rost onboard status, etc.) operate in the approver's active tenant. If the approver has no company yet, create one headlessly with rost signup --company "<name>" — no browser step.

Notes:

• The code expires after 10 minutes — rerun rost login --device if it lapses.
• No password is entered, and no access token is stored on the server; only the agent's own machine holds the session (in its OS keychain).
• Matching the code before approving is a security step: only approve a code your own agent printed.
• Approve only in a browser you control and trust — never on a kiosk or someone else's device, and sign out afterward on any shared machine. Approval grants a live ROST session tied to your Google identity, not just a code match.

Recovering a lost code

rost login --device also persists the pending exchange locally the moment it is minted — preferring the same OS keychain the finished session uses, and falling back to an owner-only file (directory 0700, file 0600) under the CLI state dir with no opt-in flag needed, since this record is not itself a bearer credential (see "Headless Linux, CI, and machines with no keychain" above for the parallel session-store behavior). If the one mint-time print above is lost, run this from a second terminal or process on the SAME machine:

rost auth device status

It reprints the verification URL, the user code, and the time remaining before the exchange expires — no network call, so it works even mid-poll. Once the exchange completes (approved), is denied, or expires, the local record is purged; rost auth device status then reports there is no pending sign-in and points back to rost login --device.

Owner pre-authorization (Pair an agent)

An owner can pre-authorize a headless agent's login instead of matching a browser code after the fact. In the app, open onboarding's Pair an agent panel and choose Start pairing — it mints a one-time pairing code (rost_pair_…, shown once, valid 15 minutes) scoped to your workspace. Hand that code to the agent and have it sign in with:

rost login --device --pairing-code <code>

The device start then anchors to your workspace. When the agent connects, its request appears in the Pending pairings list as ready to approve, and you approve it in one click — no browser user_code to read back and match. The approved session logs the agent in as you (same session shape as the typed-code flow above), so nothing about the agent's authority differs from an ordinary login --device. A pairing you did not start never appears in your list, and the plaintext code is never re-shown or returned by any read.

To see the same live pairing state over CLI/MCP, use device.pairing.list (MCP tool rost_list_pending_device_pairings) — it lists this tenant's pending pairing intents (code minted / awaiting approval) with each connected device request and whether it is one-click-approvable. It is owner/admin only and never returns the pairing code. Omitting --pairing-code keeps the ordinary unanchored flow: the agent prints a user_code and a human approves it by matching that code in a browser.

Headless Linux, CI, and machines with no keychain

By default the CLI stores the session in the macOS Keychain (on darwin). There is no built-in Windows or Linux keychain integration today — on any non-macOS host, or any machine without a keychain, the CLI errors with "No OS credential store is available" unless you opt into the file store.

On macOS, the CLI now verifies the keychain write is readable back right after login. On some headless/service hosts the keychain accepts the write but a later command's process cannot read it back (an ACL scoped to the writing binary, a re-locked login keychain, or a launchd/SSH session with no keychain), so login reports success yet the next command prints "Not logged in". When that readback fails, the CLI automatically writes the session to the same owner-only file store (directory 0700, file 0600), prints a one-line stderr notice, and later commands read it back transparently — so a headless macOS agent "just works" with no flag. For a fully unattended macOS host, export ROST_CLI_ALLOW_FILE_TOKEN_STORE=1 anyway so every command uses the file store directly.

The keychain write itself is also bounded so it can never hang login --device after a successful approval: it runs through the keychain tool's own batch command interpreter with the session supplied inline (never on the command line, so it still never appears in ps) and a fixed timeout. If that write times out or otherwise fails, the CLI kills it and automatically falls over to the same owner-only file store — again, no flag and no manual retry needed.

For headless Linux, CI runners, or any no-keychain environment, set ROST_CLI_ALLOW_FILE_TOKEN_STORE=1 to opt into the development-only plain-file token store. It is not encrypted — it writes the file with owner-only permissions (directory 0700, file 0600) and prints a stderr warning. It stores only CLI session tokens (access + refresh token), never tenant secrets, API keys, or vault refs. Treat that file as a credential: do not bake it into a shared image and do not commit it.

The CLI checks this flag on every invocation, not just login. Export it for the whole shell or CI job (so rost whoami, rost onboard status, and the rest also find the file store), not only on the login line:

export ROST_CLI_ALLOW_FILE_TOKEN_STORE=1
rost login --device

For CI, do not run an interactive device login on every job (a device code still needs a human approver, which CI does not have). The CLI stores the Supabase refresh token from login / login --device and refreshes the access token before command execution when it is close to expiry, so normal local agent sessions survive the short access-token window without repeated browser approvals. The refresh token is still a user credential; if refresh fails or is revoked, run rost login --device again. For ongoing unattended automation, prefer a seat-scoped MCP token used directly by your MCP client, and treat that client config as a secret. Such a token now defaults to a 90-day expiry, so for automation that must outlive that window, mint it with an explicit --expires-in <days> (up to 365) or, accepting the long-lived-credential tradeoff, --no-expiry — e.g. mcp install --scope seat --seat-id <id> --expires-in 365. Rotate it before it lapses (--rotate <old-token-id>), and revoke and re-mint if a runner image is rebuilt or shared.

First-run path

This is the install/auth quickstart — it gets you logged in, MCP registered, and onboarding started. It is a convenience view, not the full org-setup procedure: for the canonical end-to-end setup order beyond install, agent-reference-map is the source of truth. Read it with rost reference get agent-reference-map (step 6 below).

1. Log in: npx @rosthq/cli@latest login (or rost login --device for a headless agent) 2. Confirm identity: rost whoami 3. Create your company if you have none yet: rost signup --company "<name>" (no browser step) 4. List tenants: rost tenants 5. Select a tenant when needed: rost use <tenant-slug-or-id> 6. For an entitled additional clean company, create it from an active company session: rost tenant create --company "<name>" 7. Read the agent map: rost reference get agent-reference-map (the full canonical setup order lives here) 8. Register MCP for the client (pick a scope — --scope is required): rost mcp install --client claude-code --scope tenant-admin for setup, or --scope seat --seat-id <id> for a narrower seat token 9. Inspect onboarding: rost onboard status 10. Get the guided agent prompt: rost onboard run

Or use the one-shot helper: rost init logs in when needed, optionally selects a tenant, installs MCP, and prints the onboarding prompt. It does not run every numbered step above (it does not create your company or call onboard status) — it gets you logged in, registered, and handed the onboarding prompt. As the first-run helper it defaults to a tenant-admin token (no seats exist yet), so unlike a direct mcp install it does not need --scope; pass --scope seat --seat-id <id> if you already have a seat to scope it to:

rost init --tenant <tenant-slug-or-id> --client codex

MCP install commands

A direct mcp install now requires an explicit `--scope` — there is no silent default. Choose --scope seat --seat-id <id> (the narrowest scope, limited to one seat's Charter and permission manifest — prefer it for day-to-day operation) or --scope tenant-admin (can administer the whole company — reserve it for initial setup). Running mcp install without --scope errors and mints nothing, naming both options. (The first-run helper rost init is the exception: it defaults to --scope tenant-admin because no seats exist yet at setup; and --rotate inherits the old token's scope, so it does not need --scope either.)

mcp install never self-approves token mint or revoke confirmations. A human at an interactive terminal can review the rendered gate and answer yes; a headless session surfaces the pending confirmation and stops.

Claude Code (tenant-admin):

npx @rosthq/cli@latest mcp install --client claude-code --scope tenant-admin

Codex (tenant-admin):

npx @rosthq/cli@latest mcp install --client codex --scope tenant-admin

Cursor (tenant-admin):

npx @rosthq/cli@latest mcp install --client cursor --scope tenant-admin

The tenant-admin token administers the whole company. For day-to-day operation, prefer a seat-scoped token instead — it operates only as one seat and is limited by that seat's Charter and permission manifest. Reserve the tenant-admin token for initial setup.

Seat-scoped MCP for a specific seat:

npx @rosthq/cli@latest mcp install --client codex --scope seat --seat-id <seat-id>

The <seat-id> comes from rost command seat.create output or rost_get_responsibility_graph / rost command graph.get.

Approving the token mint

Minting a token (and the inline revoke that --rotate performs) is a human-gated authority change at the command layer. How rost mcp install handles that approval depends on whether it runs in an interactive session:

• Interactive operator (a human at a real terminal). The CLI renders the complete gate, then asks Approve mcp_token.create (confirmation <id>)? [y/N]. Only an explicit y or yes records reviewed: true, completes the mint, and prints the registration block. TTY presence alone is never treated as review; silence or decline mints no token.
• Non-interactive / headless / agent session. The CLI does not approve its own request. It surfaces the confirmation and stops, minting nothing: it prints the confirmation_id, the exact rost command confirmation.approve --json '{"confirmation_id":"<id>"}' command, and the approveVia URL when the server provided one, then exits non-zero ("pending human approval"). A human then approves it (in a browser or with that approve command) — and that approval executes the mint and returns the token in the approve output (shown once), so register it with your client from there. Do not re-run mcp install after approving: that starts a second mint and orphans the first token. The retired --skip-permissions flag is rejected, and ROST_CLI_SKIP_PERMISSIONS is ignored; neither can replace human review.

The broader rule still holds for durable changes an agent proposes — charters, decisions, compass and charter amendments — where an agent never approves its own request and a human approves the surfaced approveVia confirmation. See the confirmations-guide for the four confirmation levels and that flow.

Handling the printed token (read this before you paste anything)

The registration block mcp install prints embeds a live bearer token — a real, scoped credential. mcp install prints this block; it does not write any client config itself. You apply it, and once applied the token lands in the client's config file in plaintext:

• Claude Code: run the printed claude mcp add command — that command writes the token into Claude Code's MCP config.
• Codex: paste the printed TOML stanza into your Codex config file.
• Cursor: paste the printed JSON entry into Cursor's MCP config.

Because the token lands on disk in plaintext, treat it like a password:

• Never commit the block or the client config to version control, and never paste it into a chat, issue, or log. A leaked block grants its full scope until revoked.
• The session asymmetry matters: your CLI login session lives in the OS keychain and is cleared by rost logout. The MCP token is a separate credential written in plaintext into the client config — rost logout does not revoke it. Revoke MCP tokens separately (below).

Example shapes of what mcp install prints (token redacted as <MCP_TOKEN>; the real values, including the workspace URL, are printed by the CLI — do not hand-construct them):

# Claude Code
claude mcp add --transport http rost https://<your-workspace-url>/mcp --header "Authorization: Bearer <MCP_TOKEN>"

# Codex (config.toml)
[mcp_servers.rost]
url = "https://<your-workspace-url>/mcp"
transport = "http"
headers = { Authorization = "Bearer <MCP_TOKEN>" }

// Cursor (mcp.json)
{
  "mcpServers": {
    "rost": {
      "url": "https://<your-workspace-url>/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

Verify the MCP connection

After registering, confirm the client can actually reach the server with the new token before doing real work. Make one cheap read call scoped to your token type:

• Any valid token: call rost_list_commands with {}.
• Tenant-admin token: read the resource rost://tenant/status.
• Seat-scoped token: call rost_get_context with {} (or read rost://seat/<seat-id>/context). A seat token cannot read rost://tenant/status — that is tenant-admin only, so do not use it to test a seat token.
• Success returns a normal JSON payload (the command list, your tenant/onboarding status, or your seat context). An auth error (a 401 / "not authorized" shape) means the token did not register — re-run mcp install.

Token lifetime and rotation

Every MCP token now carries an expiry. Tokens minted by rost mcp install default to a 90-day TTL (for both tenant-admin and seat-scoped tokens); after that the token stops authenticating and you re-mint. Override the lifetime at mint time:

• --expires-in <days> — set an explicit TTL, between 1 and 365 days. Example: rost mcp install --client codex --scope tenant-admin --expires-in 30.
• --no-expiry — mint a token with no practical expiry (a ~100-year TTL). This is a deliberate loosening for long-lived automation; the CLI prints a warning. Prefer a finite --expires-in and rotate instead.

mcp install echoes the chosen expiry, and rost command mcp_token.list reports expires_in_days for every token so you can see what is about to lapse.

One-step rotation. Replace a live token in a single command — it mints the replacement, prints the new registration block, then revokes the old token:

rost mcp install --client <client> --rotate <old-token-id>

Rotation preserves the original token's scope and seat: rotating a seat-scoped token mints a new seat-scoped token for the same seat, and rotating a tenant-admin token mints a tenant-admin token — you do not pass --scope/--seat-id (and if you do, they must match the old token, or the command errors without minting). The CLI looks the old token up first, so an unknown --rotate id fails cleanly with nothing minted. In an interactive session, mint and revoke are separate gates: after approving the mint, the CLI renders the complete revoke gate and asks Approve mcp_token.revoke (confirmation <id>)? [y/N]. Only an explicit y or yes sends reviewed: true and revokes the old token. If the operator declines, or if revoking the old token fails (or the id isn't found at revoke time), the new token is already live but the old token remains live too; the CLI prints the replacement credential exactly once so it can be recovered, labels the rotation incomplete on stdout, explains the partial state on stderr without repeating the secret, prints the manual mcp_token.revoke command, and exits non-zero. Find the <old-token-id> with rost command mcp_token.list.

You can also rotate the long way (mint then revoke separately):

1. Re-run rost mcp install --client <client> --scope <tenant-admin|seat> (add --seat-id <seat-id> for a seat token) to mint and register a fresh token — a direct install requires --scope. 2. Revoke the old one (below). Rotate on a periodic cadence, and whenever the scope or seat changes.

Revoke a token

Revoke the server-side token with the command printed by mcp install:

rost command mcp_token.revoke --json '{"token_id":"<token-id>"}'

Revocation is not just end-of-session housekeeping — it is your incident-response action. Revoke immediately if a laptop is lost or stolen, the client config leaks, or the token is committed to version control. If you no longer have the original printout, find the <token-id> with rost command mcp_token.list (MCP rost_list_mcp_tokens) — it returns token metadata, never token material.

Uninstall and cleanup

Revoking the server-side token leaves a dead entry in the client config that will keep erroring. To fully tear a setup down:

1. Revoke the token (mcp_token.revoke, above). 2. Remove the ROST entry from the client config: claude mcp remove rost for Claude Code; delete the [mcp_servers.rost] stanza from the Codex TOML; delete the rost entry from Cursor's mcp.json. 3. rost logout to clear the CLI session from the keychain (this does not revoke MCP tokens — step 1 does that).

Blast radius of a tenant-admin token

A leaked tenant-admin token can administer the whole tenant, not just one seat. It can run tenant-wide setup and onboarding, staffing (rost_staff_seat), member add / remove / role-change (rost_remove_member), Charter approval (rost_approve_charter), settings changes, and further token minting (rost_create_mcp_token) across every seat in the tenant. A seat-scoped token can act only as its one seat, bounded by that seat's Charter and permission manifest. This is why a direct mcp install now requires you to choose `--scope` explicitly (no silent tenant-admin default), why you should mint the narrowest scope that does the job, and why you should reserve tenant-admin for initial setup. mcp install echoes the granted scope and its blast radius at mint time on every path. See the security-model-guide for tenant isolation, vault-backed credentials, and the seat-scoped-authority principle.

Storing the Anthropic key and other credentials

Storing the tenant model key or any other secret goes through credential ingress as a vault reference — the secret is never pasted into a prompt, config, or log. Use rost_save_tenant_anthropic_key (tenant.anthropic_key.save) for the tenant Anthropic key; other secrets go through the Settings vault-ingress flow (credential.ingress), a human-only interactive flow that is deliberately not an agent-callable MCP tool and refuses raw secrets over CLI argv. Disabling the tenant Anthropic key uses tenant.anthropic_key.disable: it is owner/admin-only, always human-gated, revokes the active credential row without reading or returning secret material, and first checks that managed Anthropic fallback is configured. rost_configure_agent_tools stages credential *requests* (provider, scope, and label only) but never accepts raw secrets. Credential storage is a gated credential_flow confirmation that a human approves. For the vault model and the security posture behind this, see the security-model-guide and the tool-access-and-vault guide; for model-bound data, BYOK provider handling, and local-client provider settings, see the ai-model-data-handling-guide; for the confirmation gate, see the confirmations-guide.

When to use MCP or CLI

• A technical operator wants to drive onboarding from a local agent session.
• A partner wants to use their own local model subscription. Read the ai-model-data-handling-guide first so the operator can verify the local provider account, retention, telemetry, and transcript settings instead of assuming ROST controls them.
• A Steward wants a local agent to inspect context, draft changes, or prepare work.
• A developer wants repeatable setup commands.

Access scopes

Tenant-admin access can help set up the company. Seat-scoped access lets an agent act only as a specific seat. Prefer the narrowest scope that can do the job — a direct mcp install requires you to choose --scope tenant-admin or --scope seat --seat-id <id> and mints nothing until you do. rost init defaults to tenant-admin (first-run setup, no seats yet), and --rotate inherits the existing token's scope. See the security-model-guide for tenant isolation, vault-backed credentials, server-side authority checks, and the seat-scoped-authority principle.

For pairing and running a local runner, see the runner-guide.

Safe operating practices (security checklist)

These are the security posture rules for operating after install — a checklist applied across the whole setup, not a competing install procedure. For the full rationale, see the security-model-guide.

1. Log in with the CLI and select the tenant if needed. 2. Read agent-reference-map. 3. Register MCP for the narrowest needed scope (prefer a seat-scoped token for day-to-day operation). 4. Start with onboarding.status or context lookup. 5. Draft changes before durable activation. 6. Route approvals through human confirmation (an agent never approves its own request — see the confirmations-guide). 7. Revoke tokens when you finish operating or the seat changes — and immediately on a lost laptop, leaked config, or committed token. (Revoking is separate from rost logout, which clears only the CLI session, not MCP tokens.)

CLI command catalog

Authentication and tenant selection

Reference and docs

--audience <human|cli|mcp|in_app_agent> (on reference list and reference search) filters guides to those tagged for that audience. When omitted, all audiences are returned.

Onboarding

rost onboard preflight [--json]
rost onboard status
rost onboard resume
rost onboard run
rost onboard source-ingest --file <path> --source-key <key> --kind <kind> --title <title> [--json]
rost onboard setup --input '<json-plan>' | --input-file <path> [--json]
rost onboard setup-status --input '<json-plan>' | --input-file <path> [--json]
rost onboard rehearse|activate --setup-application-id <uuid> ... [--json]

Every tenant-scoped onboard verb (status, resume, source-ingest, setup, setup-status, rehearse, activate — onboard run is an offline public print) uses an existing implementation-bootstrap credential first. Only an absent credential leaves the user-session path available; expiry, read errors, authentication failures, and policy refusals stop without a principal change, so a co-resident owner session cannot silently take over an active implementation run. onboard source-ingest reads one local business file client-side, base64-encodes it, and calls onboarding.source_ingest; the server computes the digest and family manifest and returns the opaque source_ref to reference from the setup plan's sources[] (paths and client digests are rejected). Two size ceilings apply to this upload and the smaller one wins. The application's command-body cap is 1 MiB for most commands, but onboarding.source_ingest gets a selectively raised cap (≈ 6.7 MB, on both the REST and MCP command transports) sized for base64 expansion (×4/3). In front of that, the hosting platform enforces a lower request-body ceiling — measured at at least 4 MiB, the largest body proven to reach the function — and rejects a larger body at the edge before ROST sees it, so no ROST error can describe that failure. The platform ceiling is what sets the maximum size. The raised 6.7 MB application cap sits above it and so never rejects a body the platform would have delivered. The 5,000,000-byte protocol bound is still enforced — a larger file is refused on that ground first — but it too sits above the reachable size, so it never decides how large a source can actually be. Only the platform ceiling does, which is why raising the 6.7 MB cap on its own would not make a bigger source uploadable. After base64 expansion the largest source file this command can carry is therefore about 3.1 MB, short of the protocol's documented 5,000,000-byte source range; reaching that full range needs the platform ceiling raised, which is a separate change. The CLI derives its pre-check from the platform ceiling and names the exact fitting size before sending — split a larger export. onboard setup submits the complete declarative plan to onboarding.setup: staging succeeds with exit code 0 and prints the pending confirmation id plus the exact approval URL (with --json, the full pending-confirmation object). onboard setup-status re-submits the identical plan to discover state through the command's idempotent contract: after approval it returns the immutable applied receipt (application id, receipt revision, input digest) without staging anything; while approval is still pending it returns the current approval card — an identical still-valid card is reused with the same confirmation id and URL, and only a changed server-derived projection supersedes the stale card and mints a fresh one. After application, a same-key re-submission with a different plan digest is a typed conflict.

Implementation access

rost implementation access start|status|complete|abandon [--json]
rost implementation install-mcp --client claude-code|codex|cursor [--json]

Direct command execution

Seat scope (`--seat <seat-id>`). Seat-operating commands run in a seat context. A seat-scoped MCP token already carries that context; a tenant or owner session does not, so pass --seat <seat-id> to target a specific seat — an owner can target any seat in the tenant, a member only a seat they occupy. The flag rides the x-rost-seat header out-of-band and is never part of the command body; the server resolves and authorizes the seat scope. It works on both the raw rost command <id> path and the ergonomic wrappers (e.g. rost task list --seat <seat-id>).

Regular operation wrappers

Ergonomic subcommands for everyday operation. Each wrapper is sugar over the same server-side command shown in the command-id column — it builds the JSON body from flags and routes through the same execution path as rost command <id> --json. Add --json to any wrapper for stable, machine-parseable output; without it the wrapper prints a concise line that still includes the ids needed for follow-up calls. rost command <id> --json remains the completeness floor for fields a wrapper does not expose.

These ergonomic wrappers (including the rost agent group) require rost 0.2.0 or newer — run npx @rosthq/cli@latest … to get them. Older versions can still reach every command through the rost command <id> --json floor, since command execution is server-side.

Generated verbs (0.6.0+). Every registry command now has a first-class rost <namespace> <action> verb, projected directly from the command's input schema — so namespaces that previously had no ergonomic wrapper (for example rost measurable create, rost work_order enqueue, rost mcp_token create) are usable without dropping to the raw command <id> path. Flags follow the schema field names (--seat-id, --name, …); read a command's exact input offline with rost <namespace> <action> --schema before calling it, and pass a nested payload with --input '<json>' or --input-file <path> (a JSON file read client-side) when a field is a complex object — explicit field flags merge on top of either payload form. On these generated verbs, a flag the verb does not support is a usage error naming the flag before anything is sent, never silently ignored (the bespoke handler verbs, such as status record and agent create, still parse flags by hand and are being hardened separately). --json still selects machine output, --seat <id> still sets seat scope, and rost command <id> --json '<body>' remains the universal fallback.

For a complete Seat, inspect rost seat create-complete --schema, then pass the strict nested request with rost seat create-complete --input '<json>' --json. The generic rost command seat.create_complete --json '<json>' path and the generated MCP tool rost_create_complete_seat expose the same registry schema and server-side command. seat create-complete uses an existing implementation-bootstrap credential first (it is one of the vetted bootstrap staging primitives); only an absent credential leaves the user-session path available. Expiry, read errors, authentication failures, and policy refusals stop without a principal change. Staging is the success outcome for this verb: the CLI exits 0 and prints the pending confirmation id and the exact approval URL (Approve once: <url>), and with --json it prints the pending-confirmation object verbatim for machines — the command has done its job at that point. The raw rost command seat.create_complete --json '<json>' path renders staging the same way — the pending-confirmation JSON on stdout, exit 0. The human owner reviews one card covering the Seat, canonical Charter and permission manifest, disclosed staffing, effective agent lane/readiness, exact pinned Skill versions and dependency state, and schedule. Approval applies the proposal in one transaction and returns its application and receipt ids. Any failure rolls back the whole proposal. An optional agent remains in dry_run; this command never approves go-live. Direct calls use existing parent and Steward Seat ids—logical references are reserved for the later composite onboarding flow. Retained source ingestion is not available on this direct command yet, so sources and every source_uses collection must be empty and planned staffing must omit source_ref; the command rejects source-backed provenance instead of accepting an unverified upload id or caller-supplied digest.

The signed-in app exposes the same Skill command surface at Skills, linked from the Agents page (the nav collapse moved it out of the primary sidebar). Use /skills to filter the tenant library, /skills/new to build canonical SKILL.md frontmatter with tool.catalog dependencies, /skills/import for bounded GitHub or upload imports, and each Skill detail page to review validation, publish, check Seat dependencies, and assign a published version. During /agents/new, agent_setup.get can return next_action: "choose_skills"; selected Skills are proposed immutable-version assignments and required Skill tools block sign-off/go-live until tool configuration is ready.

Skills wrapper help:

rost skills list [--json]
rost skills catalog [--json]
rost skills get --slug <slug> [--json]
rost skills file --slug <slug> --path SKILL.md
rost skills enable rost/<slug> [--json]
rost skills install <slug-or-rost/slug> [--seat-id <id>] [--client claude-code|codex|cursor] [--version <n>] [--local-only] [--json]
rost skills install-implementation [--client claude-code|codex|cursor] [--tag <tag>] [--json]
rost skills sync --seat-id <id> [--client claude-code|codex|cursor] [--json]
rost skills assign --seat-id <id> (--skill <slug>|--slug <slug>|--skill-version-id <id>) [--approve] [--allow-blocked-proposal] [--json]
rost skills revoke (--assignment-id <id>|--seat-id <id> --skill <slug>) [--json]
rost skills publish (--slug <slug>|--skill-version-id <id>) [--allow-warnings] [--json]

rost skills install writes into the client Skills directory and records .rost-skill.json with skill_version_id, content_sha256, source, client, and installed_from: "rost_api". Set ROST_SKILL_INSTALL_ROOT to override the local root in CI or a sandbox. Use install for one Skill and sync as the default local-agent command because it installs every approved Skill assigned to the Seat and skips a local copy only when its recorded hash matches and the installed file's own sha256 and byte size verify against the package the server returned; an edited or truncated local file is reinstalled instead of being reported unchanged. For --client claude-code the root is $CLAUDE_CONFIG_DIR/skills — CLAUDE_CONFIG_DIR is the variable Claude Code itself reads — otherwise ~/.claude/skills; CLAUDE_HOME set on its own is a usage error with a migration instruction, and CLAUDE_HOME set alongside a different CLAUDE_CONFIG_DIR prints a notice that CLAUDE_HOME is ignored. For --client codex the root is $CODEX_HOME/skills, otherwise ~/.codex/skills. For --client cursor the root is ~/.cursor/skills. Catalog Skills land under <skills root>/rost/<slug>, except under ROST_SKILL_INSTALL_ROOT, where they land under <override root>/<client>/<slug>. A whitespace-only value for any of these variables is rejected rather than resolving somewhere unintended; an empty value means unset (the shell's FOO= cmd idiom for turning an inherited variable off) and falls back to the default root above. Entitlement failures mean the tenant cannot access that ROST catalog tier yet; stale local copies are fixed by rerunning sync; private catalog access is always served by ROST APIs, not by giving the agent a private GitHub credential.

ROST-maintained catalog entries are seeded from first-party Skill packages with stable content hashes, application descriptors, and declared required or optional tool dependencies. Catalog seed validation is fail-closed: a package with parser warnings is not published. Enabling a catalog Skill copies the current immutable version into the company library; later catalog refreshes update the global catalog row but do not silently rewrite already-enabled tenant Skill versions.

MCP registration

MCP tool and resource catalog

This catalog is the canonical machine surface — the rost_* tools your MCP client calls. Three different things are called "tools" in ROST; do not confuse them:

1. The MCP tools below — the rost_* surface your client actually calls to read and act. 2. `rost tools list` / `tool.catalog` (MCP rost_list_tool_catalog) — the agent-configuration catalog the builder reads when staffing an agent. It includes scope tiers, provider-neutral access levels, provider requirements, cost class, lane support, and Trusted metadata. It is selectable per agent, but selecting a tool is not itself a call; live handlers execute later only behind the signed manifest, guard, credentials, and bindings. 3. `rost model list` / `model.catalog` (MCP rost_list_model_catalog) — the guided model-tier catalog the builder reads for recommendations, effort, token prices, cost bands, and model id selection. 4. The "Available tools guide" (in the sidebar) — covers tool *categories* and governance, not a callable surface. See the available-tools-guide.

Sections below: Command discovery (2) · Public reference (3) · Tenant-admin tools (grouped by domain) · Seat-scoped operating tools (9) · MCP operation resources (13).

Command discovery tools

These read-only tools are available to any valid MCP token (like the reference tools). Use them to discover a command's exact contract before calling it, and when a command fails, read the error's help field and run the command it names.

The equivalent CLI verbs are rost command schema <id> and rost command list. The discoverable tool catalog is rost tools list (MCP rost_list_tool_catalog, tenant-scoped).

Deferred tool schemas (JIT loading)

For tokens whose catalog of generated command tools is large, each operating command tool is still advertised in the tool listing by name with a one-line description, but its full input contract is deferred rather than sent up front — this keeps the default tool listing small for large catalogs. The description names the command's command_id. To call a deferred tool, first call rost_describe_command with that command_id to load its exact input and output contract, then call the tool with the real arguments; the tool is fully callable either way, only the delivery of that contract is deferred.

Deferral is threshold-gated: small catalogs keep their full per-command contracts with no change in behavior. The pinned core seat tools (rost_get_context, rost_escalate, rost_report_status, and the task tools rost_get_tasks, rost_accept_task, rost_decline_task, rost_complete_task) and the reference and discovery tools are never deferred.

Deferring a contract changes only what is advertised in tools/list. Authorization is unaffected: every call still passes the server-side guard against the seat's signed permission manifest and writes its audit row, exactly as described above — visibility into a tool's arguments is never a security control.

Public reference tools and resources

Tenant-admin tools

These names are available to tenant-admin MCP tokens. They are aliases over the shared command layer and are audited as MCP tool calls. The list spans far more than onboarding — it groups, in order: onboarding, seats, Charter, confirmations, Compass, staffing, credentials/tokens, graph reads, agents, runners and work orders, notifications, members and settings, Signals, Cascade goals, Friction, tasks, Sync, and escalations.

Several rows here are seat-operating commands (task.create, the signal.*, goal.*, and friction.* families) surfaced because they are also tenant-admin-callable — which is why the CLI wrapper table marks them "Seat". Scope selection follows the Seat scope note above: a seat-scoped token already carries seat context and sees only the seat-scoped MCP tools registered for that token; a tenant or owner CLI session must pass --seat <seat-id> to act in a seat context. See the security-model-guide for the seat-vs-tenant authority principle.

The web Forge control room at /forge uses the same command path for project selection, build request creation/list/detail reads, request pause/cancel/resume controls, runner capacity, configuration status, and Developer Team install. Request cards and detail pages surface scheduler_state directly: queued work shows its work-order state, parked work explains why it is parked — no paired online runner is available, the owning seat's charter manifest is not signed (charter_manifest_not_signed, blocked until the manifest is signed with charter.sign_manifest and the request is resumed), or the owning seat has no active charter (charter_missing, blocked until a draft is created or replaced with charter.set (or charter.draft + charter.update_draft), approved with charter.approve, and the request is resumed) — and not-configured work sends the operator to /settings/runners/setup. A request detail page also shows phase history, open gates, plan progress, loop/time/cost ceilings, and latest plan-review questions from software_factory.request.show; answering a clarification, approving a plan, rejecting it, pausing, canceling, or resuming calls the same Forge commands exposed over CLI/MCP. Lifecycle controls deliberately stage pending confirmations before changing runner state. The install button also stages a pending confirmation before durable seats, Skills, authority grants, or live agent activation are applied; the install page states plainly that approving activates the 7 agents at a pull-request-only, observe-first posture and surfaces the company autonomy ceiling.

#### Forge GitHub App access

Forge repository access is through a tenant-bound GitHub App installation, not through a human's ambient git or gh credentials. The server verifies GitHub webhook signatures before parsing payloads, resolves the installation and repository against active tenant bindings, records delivery ids for idempotency, and creates GitHub issue build requests only when an active repo binding and policy allow intake.

Installation tokens are short lived and are not stored. The durable record is audit metadata: installation id, repository id, requested action, policy decision, reason, and related Forge request when one exists. GitHub issue titles, labels, and bodies are treated as untrusted source content; labels may request an automation mode, but only server-side Forge automation policy can allow pr_only, merge_after_checks, deploy_preview, or deploy_production. Production deploy remains human-gated.

Tenant GitHub App connect and bind are intentionally not CLI or MCP mutation tools; only the read software_factory.github.installation.list is exposed. Start at /forge/settings/github. Connect and bind are decoupled (DER-1281): user-scoped GitHub App authorization verifies the repositories you administer server-side and records them as connected (unbound, no project) via software_factory.github.installation.connect — this persists on any successful ownership proof, not only the one-shot post-install redirect, so a missed setup redirect is no longer fatal (a persistent "Verify ownership & add repositories" action re-runs it any time). Binding is a separate, always-available step: software_factory.github.installation.bind maps a connected repository to a Forge project (no GitHub re-authorization), and software_factory.github.repository.unbind returns a repository to connected/unbound (re-bindable) or disconnects it. Token minting and issue intake only ever see active (bound) repositories, so an unbound repository never enters automation.

The Forge GitHub App itself is org-owned. App private key, webhook secret, and client secret values are platform-owned ROST operator credentials stored through the vault's reserved ROST system namespace, not through a customer tenant namespace or a tenant UUID deployment variable. Manifest conversion and manual secret storage also require the app-level GITHUB_APP_OPERATOR_EMAILS allowlist, which should contain only approved ROST platform operator emails. Deployment config carries only refs (GITHUB_APP_PRIVATE_KEY_REF, GITHUB_APP_WEBHOOK_SECRET_REF, GITHUB_APP_CLIENT_SECRET_REF); raw secret env vars are local/legacy compatibility only. The dogfood app is ROST Forge under agenticoperatingsystem with App ID 4208495 and Client ID Iv23liImH7qlBvXYQ0Wx. The base app omits administration and workflows; elevated repo creation or workflow mutation needs a separate human-approved power path.

#### Forge Vercel access

Forge Vercel access is through a tenant-bound OAuth connection, never a browser-visible token. Tenant admins start at /forge/settings/vercel; the callback exchanges the short-lived Vercel code server-side, stores the access token in the vault, and records only account/team metadata plus the vault-ref pointer via software_factory.vercel.connection.connect. Existing Vercel projects are linked through software_factory.vercel.project.link; greenfield project creation is intentionally absent from this slice and requires a future explicit authority flag.

Preview deployment creation is a governed command. software_factory.vercel.deploy_preview requires an active Vercel project link, a Vercel OAuth vault-ref connection, active deploy_preview Forge authority for the requesting seat when a seat is supplied, and any requested preview secret/config grants. It writes the deployment id, URL, commit SHA, checks, status, and error metadata into software_vercel_deployments; build-request deployments also write a Forge artifact and event. Raw OAuth tokens and vault refs are never returned.

#### Secret broker grants (tenant-level)

Generalized brokered-secret egress beyond Forge (DER-1738). A human grants an agent seat a scoped secret the secret.broker egress tool and the baserow.read/baserow.write tools (DER-1739) resolve server-side; Postgres stores only a vault-ref pointer, never secret material. A seat agent asks for and lists its own grants through the seat-scoped secret_grant.request / secret_grant.list tools (in Seat-scoped operating tools below); a human grants and revokes here. To grant, pass credential_id (from credential.list, DER-1777) instead of a raw vault_ref — the command resolves the ref server-side so no product flow ever exposes it. Baserow authenticates with an Authorization: Token <key> header, so a Baserow grant uses injection_mode: "header", injection_name: "Authorization", and injection_prefix: "Token " (DER-1785) — the broker prepends the prefix to the raw key at render time, so the credential's vault secret stays the RAW key and granting it by credential_id renders Authorization: Token <key> correctly. (injection_prefix is non-secret config, capped at 32 chars, rejects control characters, and is invalid for injection_mode: "header_bearer", whose Bearer prefix is implicit.) Older grants that instead stored the full Token <key> string as the vault secret with no prefix still work — the broker injects that verbatim.

Seat-scoped operating tools

Seat-scoped MCP tokens expose the operating protocol below. The server still checks the seat's permission manifest, Charter, task ownership, and tenant boundary. These are the seat-token equivalents of the CLI rost task / rost signal / rost friction wrappers and the tenant-admin task tools above: rost_get_tasks, rost task list, and task.list are the same operation reached three different ways. The command-id column makes the mapping explicit.

When the vision is withheld

A seat-scoped bundle validates the stored document before handing it to you, so one that no longer matches the published contract is never passed off as the live vision. Read the compass_status field (ok / absent / invalid) rather than inferring from a null document — the two are different situations and only the status tells them apart. The full contract, and what to do in each case, is in the compass-authoring-guide under "When the vision is withheld".

MCP operation resources

These read-only resources bundle the facts the UI shows so an agent can avoid guessing ids. Each enforces tenant, role, and seat scope server-side and never returns secrets, tokens, local file paths, or cross-tenant ids. Tenant-wide resources require a tenant-admin token; the seat-context resource is readable by the owning seat token (or a tenant-admin for any seat in the tenant); the operations map is public to any valid token.

Troubleshooting

These rows are quick, at-a-glance triage. For deeper auth, tenant, scope, confirmation, and MCP-token errors — including structured error-code interpretation — see the troubleshooting-guide.

• Not logged in: run rost login, then retry rost whoami.
• Session not persisting (keychain issue — "not logged in" right after a successful login): clear and re-run rost login --device; the session is stored in the macOS Keychain by default. On a non-macOS or no-keychain host the CLI errors unless you opt into the plain-file token store — see Headless Linux, CI, and machines with no keychain.
• Wrong tenant: run rost tenants, then rost use <tenant-slug-or-id>.
• Missing Node: install Node 22 or newer, then rerun npx @rosthq/cli@latest --help.
• Node present but too old (npx launches but the CLI rejects it): run node --version; if it is below v22, upgrade Node.
• Stale npx cache: rerun with npx @rosthq/cli@latest --help or clear the npm cache.
• MCP connection not working after registering: call rost_list_commands with {} (any token); with a tenant-admin token read rost://tenant/status, with a seat-scoped token call rost_get_context with {} (a seat token cannot read rost://tenant/status). A 401 / not-authorized shape means the token did not register — re-run mcp install.
• Revoked, expired, or invalid MCP token: run rost mcp install --client <client> --scope <tenant-admin|seat> again to mint and register a fresh one (a direct install requires --scope; or rotate the old token in place with --rotate <old-token-id>, which inherits its scope). Tokens minted by mcp install default to a 90-day expiry — check expires_in_days in rost command mcp_token.list; mint with --expires-in <days> or --no-expiry to change it.
• Confirmation required: a human approves from the approveVia web link or runs the rost command confirmation.approve --json ... command shown in the CLI error output (an agent never approves its own request — see the confirmations-guide).
• Command denied by scope or manifest: switch to a tenant-admin token for setup, or ask a human Steward to update the seat Charter and permission manifest.
• Inference budget hard cap reached (a run stops with a budget precondition error): raise the tenant hard cap with rost settings update --hard-cap-usd <amount> (command settings.update), then retry. A new company starts at a $0 hard cap, so managed-inference runs are blocked until it is set. The sandbox dry run is free and is never blocked by the cap, so you can charter, dry-run, and go live before setting a budget.
• Need command guidance: run rost docs, rost reference search "onboarding", or rost reference get agent-reference-map.
• Need MCP guidance: call rost_reference_get with {"slug":"agent-reference-map"}.