Staff & Agents

Prerequisites

What must be true before a Staff actor can take work — model provider, agent-eligible runner group, seats, and optional storage

An actor that cannot call a model, or cannot land on a runner, will sit idle. Staff's inbox shows a first-run checklist until the three blocking items below are done. Storage is optional.

Open the console at staff.orkestia.dev. Connections are not created in Staff — they live in the main app at app.orkestia.dev/connections.

1. Connect a model provider (required)

Sessions reason with an LLM from your provider connection. Orkestia does not host the model.

Counted as a model provider:

Connection type	Typical use
`openai`	GPT family
`anthropic`	Claude
`azure_openai`	Azure-hosted OpenAI
`google_ai`	Gemini
`minimax`	MiniMax
`mistral`	Mistral
`fireworks`	Fireworks
`together`	Together
`groq`	Groq
`cohere`	Cohere

After the connection exists, Staff can list model profiles for that org. Hire and config screens need a profile UUID — that is how the session knows which model to call.

Bedrock and other cloud-native AI connections may exist in the platform catalog without ticking this checklist. If hire cannot see a profile, use one of the types above or confirm the connection validated in the main app.

TypeSafe is not a model provider. A TypeSafe connection does not appear in the table above and must not be used as the actor's LLM. Connect it in the main app, then let the actor call typesafe.systemone.evaluate through MCP when it needs a closed-set decision.

2. Create an agent runner group (required)

Sessions run on runner groups you own, in your cloud. A GitHub Actions / generic compute pool is not enough.

The gate is a single signal:

agent-eligible := (runner group purpose == agent)

supports_agents on a config is enablement metadata only — it does not turn a generic group into an agent group. If you point a config at a non-eligible group, session-launch fails fast instead of hanging until heartbeat timeout.

How to get one:

In Staff, open Admin → Runner groups (/runner-groups).
Create a group for agents (not CI). Production-shaped kinds: fargate, azure_container_apps_job, kubernetes; laptop coding uses devkit. See Runner groups and Runner management.
Enable the group for agents once it is active.
Select that group when you hire or edit a config.

Details and failure modes: Agent runner groups.

3. Hire an actor (required)

A config created outside the hire flow does not count. You need at least one Staff actor in a unit. The hire wizard drafts the config from a role description, then you attach model, runner, skills, and MCP. Walkthrough: Hire an actor.

Actors occupy seats. Org-inherited actors can run with the org's permission set; custom RBAC-scoped actors consume a paid actor seat. See Identity & tokens and Billing, pricing & seats.

4. Object storage (optional)

Chat attachments need an AWS, GCP, or Cloudflare connection with a bucket. Skip this if you only need text. Staff will warn but will not block hire.

Also useful (not on the inbox checklist)

Need	Where
Org login and an organization	User onboarding
Cloud account for the runner itself	AWS connections / Cloud connections
Workflow MCP from an IDE or desktop agent	MCP integration + an `agt_` token
Agent memory	Memory & cost · Engram
Coding assignments on a laptop	Coding agents · DevKit runner

You can complete (1) and (2) in either order. Do not hire before both exist unless you are prepared to edit the config afterward — invoke will fail without a model profile and an eligible runner group.

Staff & Agents

Run AI workers in Orkestia — hire Staff actors, attach agent configs, launch sessions on your runners, and govern them with roles, approvals, and audit

Hire an actor

Turn a role description into a Staff actor — model profile, runner group, skills, MCP servers, and the first session