Agents administration

When AI agents work in your workspace - via MCP, the CLI, or an autonomous fleet - three admin surfaces give you the operational controls: Admin -> Multi-Agent (onboarding, live presence, pausing), Admin -> Agent rules (the binding instructions every agent receives), and Admin -> Agent drift (a monitor for work that slipped outside the normal ticket/commit workflow).

Personal accounts vs. service accounts

Before onboarding anything, it helps to know which kind of account you actually need - orboto models two distinct things:

• Your personal account - you, signed in through the web app, or an AI client you're driving interactively (Claude Desktop, Cursor, VS Code). One person, one identity. Authenticates via your normal login (including SSO) or a personal API key scoped to you.
• A service account - a shared identity for running coding agents unattended: one agent, or several running in parallel (for example multiple Claude Code or Codex sessions each working a different ticket at once). Authenticates via a single API key every instance shares - orboto tells the individual instances apart by a per-instance session, not by separate logins. Use a service account whenever nobody is watching the agent work, or whenever you want more than one agent running concurrently.

This distinction also decides how timers behave: your personal account has one timer - starting a new one replaces and books whatever was already running, so you never end up with an orphaned clock. A service account instead runs one independent timer per agent instance - nothing auto-stops another instance's timer, which is exactly what lets several agents track time correctly against different tickets at the same time.

Onboarding a service account (guided setup)

Admin -> Multi-Agent leads with a Guided setup: parallel agents card that walks through the whole thing in order - you need permission to manage users to run it:

1. Create or pick a service account. Either create a brand-new one (name + email, e.g. "Codex Fleet" / codex-fleet@yourteam.example) or search for and reuse an existing service account you've already set up.
2. Assign the agent role. The role needs the api:use and mcp:use permissions so the account (and every agent instance using it) can actually authenticate. The card recommends the built-in service-account role, which already includes both.
3. Mint the API key (optional - only needed if your coding agent can't complete an OAuth login on its own; step 4 covers the OAuth path instead). Name the key something you'll recognize later. It's shown once, immediately after creation, with a copy button - copy it now and store it somewhere safe, since orboto never displays it again.
4. Hand off to your coding agent. Generate a setup prompt for this account, then paste it directly into your coding agent's chat - the agent wires up its own orboto access from there (via the API key from step 3, or by completing its own OAuth login if it's capable of that).

Each step visibly marks itself done as you complete it, and later steps stay disabled/greyed out until the one before it is finished, so there's no way to mint a key for an account that doesn't exist yet or assign a role before picking who it's for.

Live presence

Below the guided setup, the presence table shows every currently active agent session - a session counts as active if it's sent a heartbeat within the last 90 seconds; older ones simply disappear from the list rather than sitting there stale. Filter with the All / Bots only / Humans only chips above the table. Each row shows:

• User - the account's name/email, with a bot or person icon.
• Runtime - the connecting client's self-reported name and version (e.g. claude-code v1.x).
• Status - working, blocked, or idle, plus a paused badge if either that specific bot or the whole workspace is currently paused (see below).
• Working on - the ticket it currently holds, if any, plus a row of small badges for every work-session lease it holds (a ticket key and role, e.g. "ACME-42 - implementation", with the lease's expiry shown on hover) and a lock-icon count of any resource claims it's granted or waiting on for that lease - useful for spotting a stuck agent that's actually blocked waiting on a file-path claim someone else is holding.
• Capabilities - tags the agent declared about itself.
• Last seen - time of its most recent heartbeat.

Work routing labels

Two ticket labels steer which tickets an autonomous agent picks up on its own - the full model (pull semantics, review lanes, feeding a fleet) is covered in Work routing and fleets; the short version, shown right on this admin page next to the pause switch:

• human - a hard lock. Agents never pull this ticket on their own. A human can still explicitly hand it to an agent, which then sees a clear warning that it's working reserved work.
• agent:<tag> - a preference, not exclusivity. Agents pulling with that specific tag get first crack at the ticket; other agents still take it if nothing better is available. A ticket with no label at all is open to any agent by default (opt-out, not opt-in).

Pausing

Two independent switches stop self-directed agent work, both visible on the Multi-Agent page:

• Per-bot pause - a Pause/Resume icon next to any bot's status badge in the presence table stops just that one agent identity from pulling new work on its own; anything already explicitly assigned to it keeps running. The same toggle is also available per-bot in the user editor under Admin -> Users.
• Workspace-wide pause ("Autonomous work") - one switch at the top of the Multi-Agent page stops every agent's self-directed pulls at once, instantly. This is the one to reach for during a maintenance window or an incident - explicitly assigned work still runs even while paused; only agents picking up NEW work on their own initiative stops.

Agent rules

Admin -> Agent rules manages the binding working-rules every external coding agent (Claude Code, Cursor, headless bots, any MCP client working in a repo) receives when it connects or runs orboto init. This is distinct from the AI Chat assistant, which runs on its own fixed internal prompt and never reads these rules.

Each rule is a block with a title and body text. Per rule:

• Reorder with the up/down arrows on the left - order matters, since rules are assembled into one document in this order.
• On/off checkbox - a disabled rule is skipped entirely when assembling what an agent receives.
• Edit the title inline, and the body in the textarea below it (saves when you click away).
• Targeting (the crosshair icon) opens a panel to scope a rule so it only applies to specific agent kinds (suggested values: coding, orchestrator, reviewer, runner, chat) and/or model tiers (frontier, standard, small) - leave both empty for "everyone." You can type your own values beyond the suggestions too. A rule with any targeting shows a small amber tag summarizing it right in the list, so you can spot scoped rules at a glance without opening every panel.
• Per-tier body variants - inside the same targeting panel, give a specific model tier its own alternate wording that replaces the default body just for that tier (e.g. a shorter, more directive version for a "small" model, and a fuller explanation for "frontier"). Leave a tier's variant blank to fall back to the default body.
• Reset to default (the built-in rules only, marked "default" in the list) restores the original shipped wording, discarding any edits. Delete (custom rules you added yourself, marked "custom") removes it entirely.

Preview (top-right) shows exactly what gets assembled and sent - pick a specific agent kind and/or model tier from the two dropdowns above the preview to see precisely what THAT combination would receive, rather than guessing from the individual rule rows.

Click Add rule at the bottom to write a workspace rule of your own from scratch, the same way you'd add a custom instruction anywhere else

• give it a title and body text, save, and it's live for the next agent that connects.

A drift monitor (below) separately flags workflow drift, not rules-acknowledgment - see the next section.

Agent drift

Admin -> Agent drift tracks moments where a commit or a ticket transition happened outside orboto's normal tracked workflow - useful for catching an agent (or a human) that bypassed the ticket/timer/commit-message discipline the rest of the product assumes. It watches two specific patterns:

• Untracked commits - a commit that referenced no ticket key AND wasn't covered by a running timer or time-entry window at the time it landed.
• Transitions without a summary - a ticket's status changed with no accompanying summary comment from whoever made the change.

This feature is opt-in: nothing gets recorded until an admin sets system_config.agent_drift_detection_enabled to true. There's no dedicated toggle for this in the System Settings UI yet - set it via the system-config API/PATCH directly. Once it's off, existing recorded events stay visible on this page (marked historical); once it's on, detection resumes going forward - a banner at the top of the page tells you plainly which state you're in.

The page opens with a metrics summary: total events, a breakdown by type (untracked commits vs. transitions-without-summary), and a Top drifters panel naming the three users/bots with the most events - a fast way to spot a single misbehaving agent identity rather than scrolling the full list.

Below that, filter by type and by status (Open / Resolved / All). Each row shows when it happened, who did it (with a "bot" tag if it was an agent identity), and the specific event - a commit's SHA, message and repo for a commit-drift row, or a link straight to the ticket for a transition-drift row. Status shows Open (nothing done about it yet), Resolved (someone reviewed and dismissed it), or Retro <ticket key> (the drift was already covered by a retrospective ticket someone filed for it, linked right there). Click the checkmark on any open row to mark it resolved once you've reviewed it - there's no bulk-resolve, each row is a deliberate decision.

Troubleshooting

• A specific agent never shows up in the presence table - it hasn't sent a heartbeat in the last 90 seconds, or it never authenticated successfully in the first place; re-check the API key/OAuth wiring from the guided-setup handoff rather than assuming the table itself is broken.
• An agent keeps ignoring the human label - that label is a hard lock against self-directed pulls only; if a human explicitly assigned the ticket to that agent, it will still work it (with a warning shown to it) - check the assignment, not just the label.
• Pausing a single bot didn't stop it from finishing what it was already doing - expected; both pause switches stop new self-directed pulls, they never interrupt work already in progress or explicitly assigned.
• An agent doesn't seem to be following a rule you just added - check whether the rule is scoped via Targeting to an agent kind or model tier that doesn't match this particular agent; use Preview with that exact kind/tier combination to see precisely what it actually receives.
• Agent Drift shows nothing even though you're sure agents are committing without ticket keys - confirm agent_drift_detection_enabled is actually set to true; it's off by default and has no UI toggle today, so it's easy to assume it's already on when it never was.
• A drift event you already handled keeps showing as Open - resolving is a manual, per-row action with no automatic detection of "someone fixed this"; click the checkmark yourself once you've reviewed it, or file a retro ticket and it'll show as linked instead.