Show HN: Seahaven – Open-source framework for building RL environments

Kiln-AI released Seahaven, an open-source Python framework for building synthetic RL and evaluation environments in which each agent run gets its own isolated, stateful SQLite-backed world. Seahaven serves hundreds of world instances per process at thousands of requests per second, logs every row an agent changes for state-based grading, and reproduces runs from the same fixture, clock and random seed; it exposes environments via OpenEnv and MCP and is installed with the command `uvx seahaven new crm_world`.

Quick Start quickstart • Docs https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/index.md • Examples Evals and RL need thousands of agent runs, each isolated, starting from a known state, and graded on what the agent changed. Production systems can't do that. Seahaven is a Python framework for building synthetic worlds that can: working copies of your agent's tools, realistic enough that the agent can't tell the difference. Seahaven handles the hard parts: parallel instances, reproducibility, serving, and change logs. You only write what's specific to your world: its tables and its tools. Named after the town in The Truman Show : an entire world built so that one inhabitant believes it is real. - Recreate Any Environment https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/authoring.md writing-a-tool : Mock AI tool calls, REST APIs, sandboxed SQL, search, or any custom format. - Stateful https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/concepts.md instance : Each instance of a world has its own independent SQLite database. - Composable composing-worlds : Compose, reuse and share worlds. Example: MyCoWorld can include StripeAPIWorld https://github.com/Kiln-AI/stripe world and ShopifyAPIWorld. - Fixtures https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/db schema and fixtures.md : Freeze known starting states like small startup , agency or big co , and reuse them across runs. - Concurrent Instances https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/serving and openenv.md : Serve hundreds of world instances per process, at thousands of requests per second. - Evaluate World State https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/state.md : Grade on state, not on transcripts. Every row the agent changed is logged. - Reproducible https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/concepts.md reproducibility : Same initial state fixture , same clock/time, same random seed: the same run, every time. - OpenEnv serve-with-openenv : seahaven serve is an OpenEnv environment. Drive it with any OpenEnv client, in any language, or publish it to Hugging Face. - Web Console https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/serving and openenv.md the-web-console : seahaven serve includes a web UI: open instances, call tools, and inspect state in your browser. - MCP use-with-mcp-clients : seahaven mcp serves one world to an MCP client, so you can work against it by hand from an editor or chat app. - Built for Coding Agents build-worlds-with-your-coding-agent : Docs optimized for agents authoring worlds. seahaven check tells an agent the exact fix for every mistake. - Just Python https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/authoring.md writing-a-tool : Tools are just functions. Tests use pytest. Your agent already knows how to write and test Seahaven worlds. | | Seahaven | Production or staging | Hand-written mocks | |---|---|---|---| | Realistic tools and data | ✅ | ✅ | ❌ | | Stateful across arbitrary tool calls | ✅ | ✅ | ❌ | | A private instance for every run | ✅ | ❌ | ✅ | | Hundreds of parallel instances | ✅ | ❌ | ✅ | | Every run starts from a known state | ✅ | ❌ | ✅ | | Reproducible | ✅ | ❌ | ✅ | | Every change logged for grading | ✅ | ❌ | ❌ | | Safe for the agent to break things | ✅ | ❌ | ✅ | Create a world. This writes a complete project: schema, tools, tests, a fixture generator, and an AGENTS.md that points your coding agent at the docs. uvx seahaven new crm world your world name cd crm world && uv sync Write your world. A world is a schema and a set of tools. Here is a small CRM: python import seahaven world = seahaven.World name="crm", version="1.0.0", schema=""" CREATE TABLE contacts id TEXT PRIMARY KEY, email TEXT NOT NULL, stage TEXT NOT NULL, updated at TEXT NOT NULL STRICT; """, state format="seahaven.state/1", @world.tool def create lead ctx: seahaven.Ctx, email: str - dict str, str : """Add a contact to the pipeline as a new lead.""" lead = {"id": ctx.ids.uuid , "email": email, "stage": "lead", "updated at": ctx.clock.iso } ctx.db.execute "INSERT INTO contacts VALUES ?, ?, ?, ? ", lead.values return lead @world.tool def list stale leads ctx: seahaven.Ctx - list dict str, object : """List leads nobody has touched in 30 days.""" return ctx.db.rows "SELECT FROM contacts WHERE stage = 'lead' " "AND updated at < strftime '%Y-%m-%dT%H:%M:%fZ', 'now', '-30 days' " Freeze a starting state. A fixture is a frozen database that every run starts from: with world.instance now="2026-06-01T09:00:00.000Z", clock mode="fixed" as inst: for n in range 500 : inst.call "create lead", email=f"lead{n}@example.com" inst.freeze "big co", "A pipeline of 500 new leads." Run your agent. Each run gets a private copy of the fixture in milliseconds. The same seed replays the same run, and what the agent changed is a document you grade: for rollout in range 100 : with world.instance "big co", seed=rollout as inst: run agent inst your agent, your harness reward = grade inst.state every row the agent changed Serve it. seahaven serve hosts an OpenEnv endpoint where every connection gets its own instance. Open http://127.0.0.1:8000/console to drive it by hand. uv run --extra serve seahaven serve python from seahaven.openenv import SeahavenClient with SeahavenClient base url="http://127.0.0.1:8000" as env: env.reset fixture="big co", seed=42 env.call "create lead", email="ada@example.com" final state = env.state the document the eval grades - ProjectTracker https://github.com/Kiln-AI/Seahaven/blob/main/worlds/projecttracker : the reference world, a fictional issue tracker shaped like Linear or Jira. Nine tables, 25 tools, full-text search, and fixtures from an empty workspace to a twelve-person agency with six months of history. Start here to learn the patterns walkthrough https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/projecttracker.md . - Stripe World https://github.com/Kiln-AI/stripe world : a mock of Stripe's Billing and Payments core, with 24 tables and 155 API operations behind the same tools as Stripe's own MCP server. It also serves Stripe's REST API, so the Stripe SDKs work against it unchanged. Build a world once and reuse it everywhere. A company world can add a payments world, such as Stripe World https://github.com/Kiln-AI/stripe world , and a chat world, plus its own tables and tools. The agent sees one tool list, and an eval grades what changed in every world from one state document. See the composition docs https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/composition.md . company.add world payments world.world, name="payments", tool prefix="pay " company.add world chat world.world, name="chat", tool prefix="chat " @company.tool def refund order ctx: seahaven.Ctx, charge id: str, channel: str - dict str, object : """Refund a charge and tell the support channel it is done.""" refund = ctx.worlds.payments.call "create refund", charge id=charge id ctx.worlds.chat.call "post message", channel=channel, text=f"refunded {refund 'amount' }" return refund seahaven serve hosts your world as an OpenEnv https://github.com/huggingface/OpenEnv environment, the open standard for RL environments. Every connection gets its own private instance. Each process can host hundreds of parallel instances. Drive it from Python, from Kiln https://kiln.tech , or from any OpenEnv client, such as OpenEnv's own generic client: python from openenv import GenericEnvClient from openenv.core.env server.mcp types import CallToolAction with GenericEnvClient base url="http://127.0.0.1:8000" as env: env.reset fixture="big co", seed=7 create = CallToolAction tool name="create lead", arguments={"email": "ada@example.com"} env.step create.model dump final state = env.state See the serving docs https://github.com/Kiln-AI/Seahaven/blob/main/src/seahaven/docs/serving and openenv.md for the client, the wire protocol and running in production. seahaven mcp connects a world to Claude, Cursor, or any MCP client. Explore a world by hand, debug your tools, or try a task yourself before you give it to an agent. uv run --extra mcp seahaven mcp --fixture big co Seahaven is designed to be built by coding agents. seahaven new writes an AGENTS.md that points your agent at the docs for the version you have installed, not stale ones from the web. seahaven check catches the mistakes that are easy to make and hard to notice, and names the fix. See CONTRIBUTING.md https://github.com/Kiln-AI/Seahaven/blob/main/.github/CONTRIBUTING.md for setup and the checks CI runs. MIT https://github.com/Kiln-AI/Seahaven/blob/main/LICENSE . Seahaven is built by the team behind Kiln https://kiln.tech , a free app and open-source library for building better AI products. Kiln connects to any Seahaven world: write scenarios against a fixture, evaluate https://kiln.tech/features/evals your agent on the state it leaves behind, then auto-optimize https://kiln.tech/features/auto-optimize prompts and models against those evals.