# Jetty

> Jetty is where professionals find, share, and run reliable AI workflows. You write a runbook — one markdown file that gives an agent its job, its bar for "done", and its checks — and Jetty runs it in a managed sandbox, records every run as a trajectory, and helps you improve it until it works every time.

These docs are written for builders: developers who work in Claude Code, Codex, Cursor, or Gemini CLI. Connect via the Claude Code plugin, the MCP server, the TypeScript SDK, or the OpenAI-compatible REST API.

## For agents

- [agent-instructions.md](https://jetty.io/agent-instructions.md): pasteable onboarding trigger — numbered steps, human-only handoffs, ends in a Return block. Start here.
- [MACHINE_CONTEXT.md](https://jetty.io/MACHINE_CONTEXT.md): deep reference — state model, CLI verb contracts, runbook format, anti-patterns.

- [Overview](https://jetty.io/docs): What Jetty is, who it is for, and how the docs are organized.

## Start here

From zero to a runbook you trust, in one sitting.

- [Quickstart](https://jetty.io/docs/quickstart): Get a token, install the skill, and run your first runbook in under ten minutes.
- [Find a runbook](https://jetty.io/docs/find-fork-run): Browse runbooks other builders have published and open one to start from.

## Core concepts

The mental model, in the product’s own nouns.

- [Runbooks](https://jetty.io/docs/concepts/runbooks): The hero artifact: one markdown file with the job, the bar for “done”, and the checks.
- [Workflows & steps](https://jetty.io/docs/concepts/workflows-and-steps): How a runbook becomes a running workflow: the author → run → investigate → improve lifecycle, and what Jetty assembles around every run.
- [Trajectories & evaluation](https://jetty.io/docs/concepts/trajectories-and-evaluation): Every run is a trajectory. Evals turn runs into a hill-climbing loop with /optimize-runbook.
- [Architecture](https://jetty.io/docs/concepts/architecture): One API, two modes (passthrough proxy and runbook sandbox), durable execution, object storage.

## Integrations & connections

Six layers you can plug into: models, agents, gateways, SDKs, frameworks, and storage.

- [Overview](https://jetty.io/docs/integrations): How Jetty connects at five layers — models, agents, AI gateways, SDKs & frameworks, and cloud storage.
- [Claude Code plugin & skills](https://jetty.io/docs/integrations/plugin): Install the plugin, run /jetty-setup, and drive Jetty with /jetty, create-runbook, optimize-runbook.
- [MCP server](https://jetty.io/docs/integrations/mcp-server): npx -y jetty-mcp-server — 16+ tools across Cursor, VS Code, Windsurf, Zed, Codex, Gemini CLI.
- [Client SDK](https://jetty.io/docs/integrations/sdk): @jetty/sdk for TypeScript: JettyClient, runAndWait, and the run → check → fix → rerun loop.

## Agent framework

Run your agent on Jetty — or anywhere, and evaluate on Jetty.

- [Bring your own framework](https://jetty.io/docs/agent-integrations): Keep your agent in any framework; use Jetty as the independent grader, store, and A/B harness. Flue and eve worked examples.
- [Flue + Jetty](https://jetty.io/docs/agent-integrations/flue): The complete flue-jetty walkthrough: grade every Flue agent run with an independent rubric and catch a regression before it ships.
- [eve + Jetty](https://jetty.io/docs/agent-integrations/eve): Mount the @jetty/eve extension into a Vercel eve agent: live grading, a grade-steered experiment bandit, and an eval reporter. Catch a regression before it ships.
- [Runbook runtimes](https://jetty.io/docs/agent-integrations/runtimes): The four agents Jetty runs inside its own sandboxes: claude-code, codex, gemini-cli, hermes.

## Guides

Task-shaped walkthroughs for the work you actually do.

- [Writing runbooks](https://jetty.io/docs/guides/writing-runbooks): The canonical structure: frontmatter, objective, output manifest, evals, and the /create-runbook wizard.
- [Evaluating & optimizing](https://jetty.io/docs/guides/evaluating-and-optimizing): Add evals to a runbook, read the trajectories, and hill-climb with /optimize-runbook.
- [Scheduling routines](https://jetty.io/docs/guides/scheduling-routines): Run a runbook on a cron cadence so evals stay fresh as models and providers drift.
- [CI integration](https://jetty.io/docs/guides/ci-integration): Trigger workflows from GitHub Actions with eval-driven quality gates.
- [Credentials & secrets](https://jetty.io/docs/guides/connected-accounts): Provider keys and environment variables, and how sandboxed runs read them.

## Reference

Lookups and catalogs.

- [API reference](https://jetty.io/docs/reference/api): The chat-completions endpoint (two modes), routines, webhooks, and GitHub-PR APIs.
- [Machine instructions](https://jetty.io/docs/reference/machine-instructions): The runbook API surface for agents and programmatic callers: tasks, runs, init_params, trajectories, files, MCP config, sweeps, snapshots, webhooks, routines.
- [Step library](https://jetty.io/docs/reference/steps): The catalog of activities: AI models, control flow, data processing, evaluation.
- [Examples & recipes](https://jetty.io/docs/reference/examples): Copy-paste workflow JSON and agent recipes for common tasks.
- [Troubleshooting & gotchas](https://jetty.io/docs/reference/troubleshooting): Common failure modes — parameter mismatches, token handling, runtime quirks — and fixes.

## Source

- [jettyio/jettyio-skills](https://github.com/jettyio/jettyio-skills): Claude Code plugin, skills, and the MCP server.
- [jettyio/jetty-sdk](https://github.com/jettyio/jetty-sdk): the TypeScript client SDK and the Flue integration example.