Staff & Agents
Troubleshooting
Sessions that never heartbeat, actors that will not act, runner gates, seats, tokens, and where to look next
Most first-run failures are prerequisites, not model quality. Work this list top to bottom.
Actor seems inert
- No skills. Attach a workflow-backed skill that grants the tools you are asking for. Zero skills ⇒ reason-only.
- Built-in MCP missing. If it should start Orkestia workflows, attach the built-in workflow MCP on the config.
- RBAC. The actor's role does not include that workflow. Check Roles and the unit the actor sits in.
- Paused or archived. Resume or hire a new actor.
Session never heartbeats / hangs in launch
- Runner group purpose is not
agent. Recreate or pick an agent group. Generic CI groups fail fast or (older configs) hang. Message text usually includes "not agent-eligible". - Group not active. Wait for provision; watch Runner management.
- Wrong image. A GitHub-Actions runner image will register and exit; the watch loop waits forever. Use the agent runtime.
- No group on the config. Edit the config; hire again if needed.
Hire cannot see a model
- Connection type not in the model provider list.
- Connection failed validation in app.orkestia.dev/connections.
- Refresh Staff after the connection succeeds so model profiles reload.
agt_ / MCP calls fail
- Token revoked, expired, or actor paused.
- Using a member JWT in an automation client — mint
agt_instead. - Passing another org's UUID in
initial_data. - Paid RBAC seat exhausted for RBAC-scoped actors — RBAC seats + Stripe.
whoami on MCP is the first diagnostic: org and actor kind must match the actor you minted.
Budget / cost surprises
- Session stopped on budget-check — raise the config ceiling or pause the actor.
- Cost page vs invoice: the Cost page shows agent session spend from the price catalog. The Orkestia invoice is the subscription (seats and add-ons) plus the execution and request meters above the included volume.
- Org pricing overrides on Pricing.
Approvals stuck in Inbox
- No human has the approve capability on that unit.
- Workflow is platform-locked; role grants will not move it.
- Open the run history — if it never reached awaiting-approval, it failed RBAC or schema first.
Where to read the evidence
| Surface | What you get |
|---|---|
| Staff Sessions / session detail | Timeline, tool calls, delivery context |
| Staff Audit | Org-scoped event log |
| Lumen | Logs, error groups, traces if provisioned |
get_workflow_history / MCP | Exact engine transitions |
The inbox first-run checklist hiding means you have a model connection, an agent-ish runner group, and at least one actor — it does not mean the runner is healthy. If invoke still hangs, ignore the green checklist and check group purpose and status.
Still stuck
- Prerequisites
- Agent runner groups
- Operations: monitoring
- Per-workflow errors: reference.orkestia.dev
Build a product team of actors
A pattern for running one product with Staff actors. A manager, a product manager, an engineer, a reviewer, QA and a release manager work from tickets, humans approve merges and releases, and a support actor answers people in the product's chat
App Host
Host your Orkestia app — website, App Data, Files on site MinIO, and a Nostr Buzz relay — from the console, without running your own cluster.