Skip to main content
Every agent in Orkestral runs on top of an adapter. An adapter is the bridge between an agent and the actual brain that thinks and writes code: a local CLI like Claude Code, a managed cloud service like Cursor Cloud, or the bundled Orkestral Forge model that executes patches at zero API cost. When you hire an agent, you pick its adapter and a model, and from then on every message and every issue that agent works on flows through that provider. This page explains what an adapter is, lists the ones you can choose from, and shows how an agent uses one in practice.
Adapters are about where the work runs, not what the agent is for. The role (Tech Lead, Backend, QA) shapes the agent’s behavior and prompts. The adapter decides which engine answers. You can give two agents the same role but different adapters.

​
What an adapter is

Internally, an adapter is a small module that knows three things about a provider.

Descriptor

Name, description, icon, and flags shown in the agent picker. Also the config fields the provider needs (for example reasoning effort or a command override).

Models

The list of models you can pick for that provider. Some are discovered live from the CLI, others come from a versioned list.

Test

A “Test now” probe that checks the provider is installed, authenticated, and responsive before you rely on it.
Each adapter carries a couple of capability flags that change where it can be used.
An executor-only adapter can run code changes but cannot be the orchestrator or plan work on its own. Orkestral Forge and the OpenClaw Gateway are executor-only. Use them on specialist agents that apply patches, not on your CEO orchestrator.
The set of provider-specific fields rendered when you create or edit an agent. The form changes as you switch providers. A provider with no schema (like Forge) needs nothing configured.

​
Available adapters

The picker is grouped: recommended providers first, then other local CLIs, then config-driven remote providers. The most common choices are below.
The claude CLI from Anthropic, running locally. Recommended.
  • Models: a default that follows your CLI config, explicit versions (Claude Opus 4.8, Opus 4.7, Sonnet 4.6, Haiku 4.5), and tier aliases (opus, sonnet, haiku) that always resolve to the newest model in that tier.
  • Config: reasoning effort (low/medium/high), a browser tools (Chrome) toggle, an instructions file path injected into the system prompt, and a command override if claude is not on your PATH.
  • Setup: install with npm i -g @anthropic-ai/claude-code and sign in with claude login.
Other providers in the registry include OpenCode and Pi (multi-provider local CLIs that use provider/model ids), Grok Build, and Hermes Agent. Two are config-driven remote providers selectable today with execution as a follow-up: Cursor Cloud (a managed remote agent that needs a repo URL and CURSOR_API_KEY) and the OpenClaw Gateway (a remote executor over a WebSocket gateway, executor-only).

​
How an agent uses an adapter

When you create an agent you choose an adapter and a model, and Orkestral stores that choice on the agent. From then on the relationship is one agent, one adapter at a time.
1

Pick the provider

In the agent form, choose an adapter from the grid. Recommended providers (Claude Code, Codex, Orkestral Forge) appear first.
2

Choose a model

Orkestral asks the adapter for its model list and shows it. Every list includes a Default option that follows whatever the CLI itself is configured to use, so you can leave the choice to the provider.
3

Fill provider config

The form renders the adapter’s config fields. These differ per provider: reasoning effort, a sandbox toggle, an instructions file, a command override, a repo URL. Required fields are marked, and the values persist on the agent.
4

Test now

Run the probe. Orkestral checks the CLI is on your PATH, runs a version check, and (for Claude Code) fires a tiny “respond with hello” prompt to confirm auth. You get a pass, warn, or fail with a human-readable checklist.
5

Put the agent to work

Once the agent is live, every chat message and every assigned issue runs through its adapter. Switch providers later by editing the agent.

​
Reading a test result

The probe returns an overall status plus per-check detail, so you can see exactly what is missing.

Pass

Installed, authenticated, and responsive. The agent is ready to work.

Warn

Usable but something needs attention, for example you are not logged in yet, the probe timed out, or a remote provider still needs its URL and token.

Fail

A hard blocker, usually the CLI binary is not on your PATH. The detail tells you how to install it.
If a check fails because the binary is not found, you do not have to add it to your global PATH. Most adapters expose a command override field where you can paste the absolute path to the CLI.

​
Choosing the right adapter

A few rules of thumb based on what each provider is built for.
Use a planning-capable premium provider like Claude Code or Codex. Do not use an executor-only adapter (Forge, OpenClaw Gateway) here, since the orchestrator needs to plan and delegate.
Use Orkestral Forge. It runs locally at $0 API cost and is built to turn an approved plan into a validated patch. Pair it with a premium planner.
Pick the adapter that fronts it: Gemini models through Gemini CLI, OpenAI models through Codex, or a mix through multi-provider CLIs like OpenCode and Pi.
Look at Cursor Cloud or the OpenClaw Gateway. These are config-driven and validate their connection on first real use rather than during the probe.

​
What to do next

Hire your first agent

Create an agent, pick its adapter and model, and run the test.

Set up the Forge

Learn how the bundled local model executes patches at zero cost.

Understand orchestration

See how the CEO plans and delegates across agents and adapters.

Track work as issues

Assign issues to agents and watch their adapters execute them.