Runtime Configuration

When Jetty runs a runbook, it executes a coding agent inside a managed sandbox. You choose which agent and which provider backs it. The following configuration options will determine how the runbook is executed.

• The AI Gateway determines which model provider will generate the tokens required. Each provider has their own addressing scheme for models. Jetty uses an OpenRouter compatible gateway by default.
• The Sandbox is a virtual machine. A default sandbox is specified that comes with common software packages and libraries (e.g. Python and Node), a web browser and LibreOffice.
• Agent Runtimes: sometimes called the agent harness, is the command-line tool that runs the runbook. The model takes input in the form of text and images and the agent provides the memory, and loop orchestration.
• Model. This is the foundation model used by the agent. You can try different models with the same runbook and evaluate performance.
• MCPs & skills are additional plugins that give the agent specialized capabilities: web browsing, spreadsheet manipulation, access to Google Workspace, etc.

AI Gateways

AI providers (or model providers) are the backends Jetty calls for inference, both from the passthrough proxy and from the model steps inside an AI workload. Each needs a key on the collection; configure them in Settings → Bring Your Own Key.

What each model_provider needs on the collection:

vllm is the catch-all for a self-hosted or custom endpoint — vLLM, SGLang, TGI, LiteLLM, or any OpenAI- or Anthropic-compatible server. Which wire it must speak depends on the runtime, as noted on each runtime's page. Not every model needs a card of its own, either: the passthrough proxy and the litellm_chat / litellm_batch actions route to 100+ providers through LiteLLM, and the action catalog adds image and video models. See Integrations for how keys reach the sandbox.

Sandboxes

python312-uv is the default: Python 3.12 with uv, Node, Chromium and the Playwright libraries, with claude-code, codex, opencode and hermes pre-installed. prism-playwright is the same idea with Playwright and Chromium front and centre. The other runtimes install on first use, which costs a few seconds per run. A custom image or Dockerfile works too; the machine instructions cover image, pip_packages and apt_packages.

Agent Runtimes

Each runtime executes inside the sandbox, reads the matching provider key, and is chosen with an agent: line in runbook frontmatter or agent in a run's init_params, both covered below.

The Providers column lists the values you can put in model_provider for that runtime; MCP says whether the runtime honours mcp_servers on a task; Usage says whether token counts land on the run.

Best-effort usage means the runtime doesn't emit token counts reliably, so a null or zero usage on the run is not a failure signal. New to this? Stay on claude-code until you have a reason to switch.

Models

The model is the foundation model the agent calls: text and images in, text out. Name it with model in the provider's own format, paired with the model_provider that serves it; each runtime's page lists the formats it accepts. Because the model is a setting on the run rather than part of the runbook, you can run the same runbook on several models and compare the runs.

Below are some models Jetty users run frequently.

A model's Tier is a rough positioning, in terms of price and speed. Generally faster models are cheaper. Opus-class models are blocked on the free trial, so they need your own key. Anything else in the OpenRouter model directory works too, with model_provider: openrouter. There are three places to set the model.

Runbook Frontmatter sets the default

A runbook names its runtime in frontmatter, so the choice travels with the file:

---
agent: claude-code                 # claude-code | codex | gemini-cli | antigravity | opencode | hermes | pi | goose
model: anthropic/claude-sonnet-5   # slug in the provider's own format
model_provider: openrouter         # anthropic | openai | bedrock | openrouter | google | vllm
snapshot: python312-uv             # python312-uv | prism-playwright
---

Leave all of them out and you get claude-code on anthropic/claude-sonnet-5 via openrouter in the python312-uv sandbox. Set model without model_provider and Jetty picks the provider: OpenRouter if the collection has an OPENROUTER_API_KEY and the runtime supports it (codex is excluded; see its page), then Bedrock if there is an AWS_BEARER_TOKEN_BEDROCK, then the runtime's native provider — Anthropic for claude-code, OpenAI for codex, Google for gemini-cli and antigravity. opencode, hermes, pi and goose have no native provider, so name model_provider for them. Naming it is the safe habit everywhere; the inference is a convenience that will eventually go away.

Override it per run

The frontmatter is a default, not a lock. When you deploy a runbook, Jetty stores agent, model, model_provider and snapshot as init_params on the task, and the run step reads them from there. Whatever you send when you start a run merges over those defaults, caller wins. So a deployed runbook can run on another agent, model or provider without a redeploy and without a second copy of the file. That is what turns a model sweep into a loop instead of a project.

Two ways to send them. From the run endpoint, pass init_params:

curl -X POST https://flows-api.jetty.io/api/v1/run/my-collection/cbc-homepage-summary \
  -H "Authorization: Bearer $JETTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "init_params": {
      "agent": "antigravity",
      "model": "gemini-3.7-flash",
      "model_provider": "google",
      "agent_env": { "ANTIGRAVITY_EFFORT": "medium" },
      "vars": { "url": "https://www.cbc.ca/" }
    }
  }'

The run form in the web app and the run-workflow tool in the MCP server send the same init_params, so anything below applies there too.

The on-ramps

Every on-ramp hits the same backend ( https://flows-api.jetty.io ) with the same token, and the API is OpenAI-compatible, so you can start with the plugin today and drop down to the SDK or REST API later without changing anything server-side. Each of them can send the same init_params.

MCPs & Skills

Every runtime brings its own core tools: file editing, a shell, and web navigation. MCP servers and skills extend that set. A task can attach MCP servers, declared as a local command or a remote HTTP endpoint, for capabilities like browser automation, spreadsheet manipulation, or Google Workspace access; the MCP column in the runtime table shows which runtimes honour mcp_servers. Skills are plain markdown, so they go inside the runbook itself. The exact shapes are in the machine instructions. Two capabilities every run relies on, whichever runtime you pick, are files and the web.

File management

In: attach files to a run directly, or pre-stage them through the upload API and pass the returned storage paths. Either way files are mounted at /app/assets/ in the sandbox, and zips are auto-extracted.

During: the agent works in /app and must write deliverables to /app/results/. This is a contract, not a convention — a run that ends with an empty results directory fails, which is the backstop against an agent chatting instead of working.

Out: everything under /app/results/ is persisted to collection storage, with the frontmatter's primary_outputs surfaced first. Fetch individual files or the whole run as a zip. Storage is per-collection and managed by Jetty.

Accessing the web

Sandboxes have network egress: agents can fetch URLs, call APIs, and install packages. Each agent is configured with permission to access the Internet. Runbooks can use services, such as Firecrawl, or run a web browser inside the sandbox to perform parts of a job.

Alternative Integrations