Agents and crews

Runtime path

Orbit runs each agent by spawning its official provider CLI as a supervised subprocess, bounded by the activity’s filesystem profile (fsProfile) and policy. The CLI talks to its provider.

This is the only execution path. The backend: http | cli | auto selector is retired; see Retired backend selection.

Providers

A provider is an agent family id, such as claude or codex. An executor is the shipped recipe Orbit uses to spawn that family’s CLI: its command, static flags, output format, and sandbox backend. The two are separate. Orbit recognizes some provider ids that have no executor, and one executor (local-shell) runs no agent at all.

Every provider id, and what it can run today:

Provider	Executor command	Reasoning `effort`	Status
`claude`	`claude`	`low`–`max`, via `--effort`	Active
`codex`	`codex exec`	`low`–`max`, via `--config model_reasoning_effort`	Active
`antigravity`	`agy`	`low`, `medium`, `high`, via `--effort`	Active
`grok`	`grok`	Model-specific, via `--reasoning-effort`	Active
`copilot`	`copilot`	Not supported	Active
`muse`	`muse exec`	`low`–`max`, via `--reasoning-effort`	Active on macOS and Linux
`gemini`	`gemini`	Not supported	Legacy
`ollama`	—	Not supported	No shipped crew or executor
`openai_compat`	—	Not supported	No CLI runtime; dispatch fails

openai_compat has no CLI runtime. ollama has no shipped executor or crew, and orbit init never seeds one. A crew that names either id still loads, but dispatch refuses it. Orbit never re-points the run at a family that has an executor.

Muse Code is the muse lane. On macOS and Linux, a crew can name provider = "muse" and model = "muse-spark-1.3"; orbit init detects its muse binary. Orbit does not ship a native Windows executor.

Orbit ships one more executor, local-shell, which is not a provider. It runs deterministic local commands for local_shell steps. It carries no model, prompt, or agent tool authority, so no crew names it. Unlike the agent executors, it declares no sandbox by default; see Platform support.

Deprecated aliases

Five legacy vendor spellings still resolve, so persisted identities keep working. Each is deprecated and emits a warning:

Alias	Resolves to
`anthropic`	`claude`
`openai`, `chatgpt`	`codex`
`google`	`gemini`
`xai`	`grok`

openai-compat is an accepted, non-deprecated spelling of openai_compat. Any other string is an unknown provider and is rejected, not guessed at.

Retired providers

The cursor, pi and opencode lanes were retired. A crew naming one fails to load, naming the crew, the retired provider and the remedy: pick a supported provider (claude, codex, gemini, grok, copilot, antigravity, muse). orbit doctor reports the same refusal. Persisted records naming them still read and display. The Cursor editor MCP client (orbit mcp init --cursor) is a separate surface and is unaffected.

Set up an executor

Pick an executor to see what it needs and a starter crew for config.toml. Each snippet is a complete example you can select and copy, with or without JavaScript.

These are examples, not availability guarantees. Orbit passes model to the provider CLI verbatim; whether your account can run it is up to that provider. Sign in to each CLI with its vendor's instructions first. Orbit can forward credentials through configured environment variables, including a global crew's env list; configure variable names, not secret values, in config.toml.

Binary on PATH: claude
Example model: opus
Reasoning effort: Supported — the full crew vocabulary, rendered as claude --effort <value>.

[workflow]
default_crew = "opus"

[crews.opus]
provider = "claude"
model = "opus"
effort = "low"
effort = "medium"
effort = "high"
effort = "xhigh"
effort = "max"

Omit effort to keep the model's default. Orbit then passes no effort argument.

Binary on PATH: codex
Example model: gpt-6.1-sol
Reasoning effort: Supported — the full crew vocabulary, rendered as codex exec --config model_reasoning_effort="<value>".

[workflow]
default_crew = "sol"

[crews.sol]
provider = "codex"
model = "gpt-6.1-sol"
effort = "low"
effort = "medium"
effort = "high"
effort = "xhigh"
effort = "max"

Codex sandbox mode and approval policy are separate settings — see execution.codex.*.

Binary on PATH: muse
Example model: muse-spark-1.3
Reasoning effort: Supported — the full crew vocabulary, rendered as muse exec --reasoning-effort <value>.

[workflow]
default_crew = "muse-spark"

[crews.muse-spark]
provider = "muse"
model = "muse-spark-1.3"
effort = "low"
effort = "medium"
effort = "high"
effort = "xhigh"
effort = "max"

Muse Code runs on macOS and Linux. Omit effort to keep the model's default; Orbit then passes no reasoning-effort argument.

Binary on PATH: agy
Example model: gemini-3.8-flash-high
Reasoning effort: Supported for low, medium, high only, rendered as agy --effort <value>.

2. Reasoning effort (optional)

omit low medium high

[workflow]
default_crew = "gemini-flash"

[crews.gemini-flash]
provider = "antigravity"
model = "gemini-3.8-flash-high"
effort = "low"
effort = "medium"
effort = "high"

xhigh and max are absent because agy --effort does not define them. Orbit ignores them with a warning instead of downgrading to high.

Antigravity model ids carry their own effort suffix and must come from agy models. A bare Gemini CLI id such as gemini-3.8-flash is rejected at config load, not rewritten into a suffixed id.

When agy is detected, orbit init also seeds a built-in argon crew on this lane (gemini-4-argon-high, enabled) and adds it to the hard complexity pool. default_crew stays gemini-flash.

Binary on PATH: grok
Example model: grok-4.7
Reasoning effort: Supported per model, rendered as grok --reasoning-effort <value>.

[workflow]
default_crew = "grok"

[crews.grok]
provider = "grok"
model = "grok-4.7"
effort = "low"
effort = "medium"
effort = "high"
effort = "xhigh"

Grok is the one provider whose effort values depend on the model. This picker shows the grok-4.7 set. grok-4.6 accepts the same four values; grok-4.5 accepts low, medium, and high, and ignores xhigh with a warning.

Effort is verified only for those three models. With any other Grok model, or no model, effort is ignored with a warning instead of being sent to a CLI that might reinterpret it.

Binary on PATH: copilot (npm @github/copilot)
Example model: claude-sonnet-5
Reasoning effort: Not supported.

[workflow]
default_crew = "copilot"

[crews.copilot]
provider = "copilot"
model = "claude-sonnet-5"

Orbit has no verified Copilot effort contract, so there is no effort picker. An effort on this crew is ignored with a warning (provider 'copilot' does not support configured reasoning effort). It does not take the workspace down or get remapped.

The retired gh-copilot gh extension is a different tool and is not an Orbit executor.

Binary on PATH: gemini
Example model: gemini-3.8-flash
Reasoning effort: Not supported.

[workflow]
default_crew = "gemini"

[crews.gemini]
provider = "gemini"
model = "gemini-3.8-flash"

This is the legacy Google lane. Individual Gemini CLI accounts stopped on 2026-06-18; enterprise Gemini Code Assist and API-key authentication still work on it. For new setups, use the antigravity executor, which orbit init picks when agy is installed.

An effort on this crew is ignored with a warning, not remapped to a nearby value.

Before your first dispatch, you also need a signed-in provider CLI and, on Linux, a working sandbox. See Install Orbit.

Tool policy

An agent_loop activity sets which Orbit tools its agent may call, in one of two modes:

Allowlist (tools): only the listed tools are callable.
Deny (tool_disallow_list): every registered agent-facing tool is callable except the listed ones. The shipped agent activities use this mode.

spec:
  type: agent_loop
  tools:
    - orbit.task.show
    - orbit.search

An empty tools: with no tool_disallow_list is deprecated and loads with a warning. Declare one or the other.

Orbit’s MCP server and orbit tool run refuse a call outside the policy, and each run records its effective tool list in the audit trail. The provider CLI’s own built-in tools stay with that CLI’s harness, inside the OS sandbox.

Crews

A crew is a named provider and model, with an optional reasoning effort. The selected crew overrides an activity’s provider, model and effort baseline. A task names a crew, and the run resolves it at dispatch: an explicit crew on the activity input first, then the task’s crew field, then [workflow] default_crew.

[crews.sol]
provider = "codex"
model = "gpt-6.1-sol"
effort = "high"

A task created without a crew gets one at creation: a draw from the pool for its purpose when configured, otherwise its complexity (workflow.<complexity>_complexity_crews), else default_crew. The task’s history records which.

A crew with an env list has its own provider account for usage limits, holds and budgets. Crews without one share the provider’s default account. Allowlisting a crew on that account does not also allow an environment-backed crew.

effort is passed through each provider’s own argument and validated against the provider and model at config load. An invalid or unsupported value is ignored for that crew with a warning, and orbit doctor lists it. Orbit never downgrades it to the nearest supported value, and orbit config set refuses to save a value that load would drop. The per-provider sets are in Configuration.

System activities Orbit creates at runtime have no crew of their own. A task pilot uses workflow.purpose_crews.task_pilot when configured, otherwise the low complexity pool; step-failure and PR conflict recovery use workflow.purpose_crews.failure_recovery, otherwise medium. Draws are kept for the run, and an empty fallback pool uses the default crew. Recovery never inherits a failed task’s crew. See Purpose pools.

With workflow.explore.enabled and an eligible workflow.purpose_crews.explorer pool, implementing and review-repair agents can ask bounded, read-only questions in their own worktree through orbit.agent.invoke. Explorers return the paths they read and cannot delegate again. This is separate from the operator’s host investigation command, orbit run agent.

workflow.mid_run_steering.enabled lets operator comments added after dispatch reach later managed prompts. A bounded checkpoint holds promotion while new guidance is undelivered. Both exploration and steering are off by default; see Configuration.

Use orbit task update <id> --crew <name> to select a crew explicitly. Automatic admission can redraw pool assignments and reassign an auto-task’s crew when a provider limit excludes it; a later operator crew change is preserved. The run records its selection; see crew pools.

With workflow.crew_selection = "usage_pressure", pool draws favour crews whose weekly allowance would otherwise go unused. The optional workflow.crew_performance setting also weights draws by per-task-type implementer performance; it is off by default. Inspect the cells with orbit agents scorecard --role implementers --by-type, or add --shadow to compare recorded shares with the performance-weighted shares. See Configuration for both settings.

Platform support

Orbit wraps each spawned agent CLI in an OS sandbox scoped by the activity’s resolved filesystem profile. orbit init writes the right backend for your host into the shipped executors:

macOS: sandbox-exec, with the profile compiled to SBPL.
Linux: Bubblewrap, from a trusted /usr/bin/bwrap or, when that is missing or too old, Orbit’s root-owned bundled build. It confines writes to the resolved profile and hides well-known credential locations such as ~/.ssh and ~/.aws. Other host reads and network access stay open, so it is not a read-rule or network boundary. Dispatch fails closed if bwrap is missing or its namespace-and-mount probe fails, unless the executor sets allow_fallback: true.
Other platforms: release binaries ship for macOS and Linux only (x64 and arm64). A source build on any other OS seeds its executors with no OS sandbox. Process supervision, tool policy, and Orbit’s in-process guards for its own built-in tools still apply.

The bundled local-shell executor declares no sandbox on any platform, by design. See Install Orbit for the Linux prerequisites.

To override a shipped executor’s own definition — its sandbox backend and fallback, the hosts it may run on (host_os), its inspection arguments or an authentication probe — edit its machine-level YAML instead of the crew. See Executor YAML.