Test your agent in CI
Regression-test a ported agent against a simulated world and gate merges on behavior change with a branded Dystopic check.
Dystopic turns "did my change break the agent?" into a pull-request check. You port your agent once as a sandbox agent, connect your repo on the platform, declare a simulated world for it to act in, and bind a suite of scenarios. On every PR, Dystopic replays that suite against both the base commit and your head commit, compares the two behaviors case by case, and posts a single branded Dystopic check that goes red only when your change moved the agent's behavior in a way your gate forbids. No live traffic, no manual QA — just a regression test for an agent, running where every other test already runs.
The mental model is platform-first: you connect your repo on the platform, and the gate and suite live on the umbrella agent — that's where they're authoritative. CI submits no config from the repo; the platform resolves how your agent boots from the connected repo, sources the bound suite's frozen scenarios server-side, and enforces the gate that's set on the agent. The only file in your repo is the workflow that invokes the check.
The seven-step flow
You wire this up once by walking the flow below top to bottom. Each step is a short, opinionated walkthrough with copy-paste commands; the deep, look-up-when-you-need-it material lives in the matching reference page and is linked from the step that needs it. Start with setup (install the CLI and authenticate) and, if the vocabulary is new, read core concepts first — it defines the nouns (agent, world, suite, check, finding) that every step below leans on.
1 · Port your agent
Wrap your existing agent so Dystopic can dispatch runs to it, and route its tool calls through the Odyssey proxy. Agents are sandbox agents — Dystopic runs your code in a managed sandbox (a CLI harness or your own Python code agent). Ends with an agent you can run locally. Port your agent →
2 · Register your agent
Register the sandbox agent on the platform — create it on the dashboard, or with the SDK (create_code_agent(...) / POST /api/agents) — then publish it to make it active. This is the umbrella agent your connected repo maps to. Register your agent →
3 · Declare the world
Define the simulated environment the agent acts in — the optional multi-agent topology and optional ledger schema, plus each tool's execution mode (Simulated / Executed / Live). A single-agent system with plain simulated tools needs neither topology nor ledger. Declare the world →
4 · Create a test suite
Author scenarios, bind them to the agent as a suite, and set the gate that decides what a behavior change is allowed to do — all on the platform (dashboard, CLI/SDK, or REST), where they're authoritative. Create a suite →
5 · Run the checks
Run the suite locally with odyssey ci review — base versus head — and read the exit code before you ever push. With --platform-suite the platform resolves the recipe and frozen scenarios for you. Iterate here until it looks right. Run the checks →
6 · Review the findings
Read the assembled review: the gate status, the per-case findings the reviewer narrated, the diff, and trace deep links. Decide what changed and why. Review the findings →
7 · Integrate into CI/CD
Connect your repo on the platform (pick the repo, install the Dystopic GitHub App, and link it to your umbrella agent), then land a real branded check on your PRs. The only file committed to your repo is the scaffolded GitHub Action. Integrate into CI/CD →
Jump in
Install & authenticate
Install the SDK/CLI and log in so every step below can reach the platform.
Core concepts
Agent, world, suite, check, finding — the nouns the whole flow is built on.
1 · Port your agent
Start the walkthrough: wrap your agent as a sandbox agent and route its tools through the proxy.
Connect your repo
The platform-first front door: connect your repo, install the Dystopic App, link your umbrella agent.
7 · Integrate into CI/CD
Land the branded Dystopic check on your pull requests.
A green check on your first PR
The very first pull request is a special case, and Dystopic handles it for you. There is no earlier commit to compare against, so odyssey ci review can't resolve a base — instead of failing, it degrades to a floor-only run: it grades only your head commit against any min_pass_rate floor you set, skips the pairwise reviewer, and reports the result as neutral unless that floor fails. The practical upshot: wire up the flow, connect your repo, open your first PR, and you should see a green Dystopic check confirming the whole pipeline is live. From the next PR onward, that same check becomes your behavior-change gate.