Runbook runtimes
When Jetty runs a runbook, it executes a real coding agent inside a managed sandbox. You choose which agent — the runtime — and which provider backs it. This is the other half of agent integrations: instead of running your agent elsewhere and grading on Jetty, you run the agent on Jetty.
Being tech-agnostic here is deliberate. The runbook is plain markdown; the runtime that reads it is swappable. If a provider changes pricing or a model regresses, you change one line, not your workflow.
The four runtimes
| Runtime | Providers | Use it when |
|---|---|---|
claude-code (default) | Anthropic, Bedrock, OpenRouter | The recommended starting point. Best general agentic coding behavior; the loop the skills are tuned against. |
codex | OpenAI, OpenRouter | You want OpenAI models driving the agent. |
gemini-cli | Google AI, Vertex | You want Gemini models, and captured token usage. |
hermes (Nous) | Bedrock, Anthropic, OpenAI, OpenRouter, Google | You want one runtime that routes across many providers from a single config. |
opencode is also available as a runtime. New to this? Stay on claude-code until you have a reason to switch.
Selecting a runtime
A runbook declares its runtime in frontmatter, so the choice travels with the artifact:
---
agent: claude-code
model: anthropic/claude-sonnet-4.6
model_provider: anthropic # or: openrouter, bedrock, …
---You can also set the agent per-run from the chat-completions API via the jetty.agent field. Make the model slug match the provider — a mismatched slug (for example a bare claude-sonnet-4-6 sent to OpenRouter) is the most common cause of a run that exits in seconds having produced nothing.
Provider keys
Each runtime needs a key for its provider, set on the collection. Configure them in Settings → AI providers, or check what's present from an agent with the check-secrets tool. See Connected accounts & secrets for the full picture, including OAuth credential forwarding.
Trade-offs to know
- Prompt style matters. Some runtimes need the runbook to imperatively demand tool use; a prose-style system prompt can cause an agent to reply conversationally and write zero files. Keep instructions action-oriented.
- Capabilities differ. Token-usage capture, streaming events, and MCP support vary by runtime, so pick based on what your runbook actually needs, then confirm with a trial run.
- When in doubt, A/B it. The bring-your-own-framework pattern works for comparing two runtimes too — same grader, different
agent:.
Next: write a runbook → or read the trajectory it produces →