roboco/docs/company/agent-gateway.md

How agents are sandboxed

The most important thing to understand about trusting RoboCo with your repository: agents never touch your API, your database, or a shell directly. Every action an agent can take goes through a narrow, server-side gateway that only exposes the handful of verbs that agent's role is allowed to use. Capability is decided by role at spawn time — not by the model's good behavior.

Agents speak in verbs, not API calls

Each agent container talks to RoboCo through two thin MCP servers, both backed by a single server-side component (the Choreographer) that composes the real services behind the scenes:

Server	What it exposes
roboco-flow	Intent verbs — the lifecycle actions: give_me_work, i_will_work_on, open_pr, i_am_done, claim_review, pass_review, complete, submit_up, submit_root, pr_pass, …
roboco-do	Content tools — commit, note, say, dm, evidence.

Two more read-only servers give agents a read-only view of git (status, log, diff) and access to the knowledge base. That's the entire surface. There is no "run arbitrary SQL," no "call any endpoint," no general shell.

A role can only call its own verbs

At spawn, every agent is handed a manifest listing exactly the verbs its role may call — and nothing else. The manifest is built from a server-side role configuration and mounted read-only into the container. The result is that the lifecycle's role rules aren't just policy, they're unreachable code for the wrong role:

• A developer can give_me_work, open a PR, mark itself done, and sync_branch (rebase its branch onto its base through the gate) — but there is no merge verb in its manifest.
• QA can claim a review and pass or fail it — but it has no commit. QA and Documenters also get i_am_blocked as their escape hatch when they're stuck.
• A PR reviewer can pass or fail an assembled PR and post its review on the PR — but it never gets agent chat verbs.
• The Auditor is restricted to leaving a private note and reading evidence; it cannot say or dm. It observes; it does not participate.

So when the lifecycle says "only QA can pass QA" or "only the CEO merges to master," that boundary is enforced at the gateway: the verb simply isn't available to anyone else.

Every action returns a structured envelope

Agents don't guess at state. Every verb returns a standardized envelope:

• On success: { status, task_id, next, evidence?, context_briefing } — where next tells the agent what to call next.
• On error: { error, message, remediate, missing } — where remediate tells the agent exactly how to fix it and retry.

That next / remediate contract is why agents move through the lifecycle reliably instead of flailing: the gateway leads them, step by step, and rejects anything out of order with an explanation rather than a crash.

The other guardrails

A few more protections run by construction, the same way on every backend (Claude or Grok):

• Claim-locking serializes work, so two agents can't grab the same task or race a merge.
• Content posts require an active claim. commit, note, say, dm, and evidence on a specific task are refused unless the agent holds that task's active claim — an agent can't write to a task it hasn't locked.
• Human-only roles are never spawned. The CEO, the Intake (prompter), and the Secretary are human-driven, so spawn_agent structurally refuses them — a notification addressed to the CEO can never launch a CEO container that acts as the human. Intake and Secretary run through their own dedicated, guarded chat paths instead.
• Notifications can't target human-only roles. notify rejects the CEO/prompter/secretary as recipients — there is no agent acknowledgement path for them, so a notification to them is a no-op rather than a stuck ack.
• The token never enters the container. Your GitHub PAT is injected only for the moment of a git operation, orchestrator-side, and scrubbed from every clone — see Register a project.
• A prompt-injection guard screens task prompts, and a bash guard blocks credential-exfiltration and identity-forgery patterns.
• Rate limits and overloads park, they don't crash-loop. If a provider returns a 429 or a persistent overload, RoboCo queues that agent's work and probes for recovery instead of burning tokens retrying. You'll see an amber banner; the work resumes automatically when the provider does.

The practical upshot for you as operator: the workforce is structurally constrained to do its job and only its job. You're not relying on twenty-five models all choosing to behave — you're relying on the fact that the misbehaving action isn't on the menu.

Next

→ Watch it all in motion in the Tour, or head back to the lifecycle.