Orangerail

Give your agent your database. Don't give it SQL.

Quickstart · Commands · What it does not govern · Against a rules file · Examples · Docs

orangerail init on a three-model Prisma schema, then a real tools/list against the server it generated. Sixteen tools: a get and a list per object, one action per write, and check_approval. Nothing on that list takes a query. The three locks are --gate delete, which is a default you change in one line, not a verdict.

A rules file cannot do this. It can ask the agent not to run a query. It cannot take the tool off the list — and we measured what the difference is worth, including the four claims that died when we did.

orangerail reads the schema you already have and generates the agent's surface from it. orangerail init turns a prisma/schema.prisma into an MCP server: a get and a list per object, one action per write with a zod input schema, and nothing else — no execute_sql, and nothing on the tool list that takes a query. It is a scanner and a code generator, with no LLM calls and no API keys. Writes you are happy to have run unattended run unattended. The ones you are not carry policy: { approval: 'required' }, which stops the call and turns it into an approval a person can act on later — including a person who is not you, after the conversation that produced it has ended.

Bounded is not safe, and this README will not pretend otherwise. A generated surface buys a reach that is finite and legible, not a claim that nothing harmful is inside it. You declared the verbs, so a destructive verb you declared is a verb the agent can call.

One precondition decides whether any of this is worth installing: orangerail governs only its own tools. If the agent also has a shell with credentials or a second database MCP server, it can go around the rail — see what orangerail does not govern.

Pre-release and installable: 0.1.5 on npm — orangerail (the CLI) plus orangerail-core, orangerail-mcp, orangerail-docs-gen and orangerail-studio. The API will move before 1.0, and Status has the one upgrade note that matters.

See your whole domain as a map

One command, and the surface init generates is a map you can read.

$ orangerail studio
orangerail studio: scanning ontology — 9 object(s), 27 action(s)
orangerail studio: building the interactive map…
orangerail studio: serving on http://127.0.0.1:4820 — open it in your browser

Every object, how they relate, and every write action an agent can reach. Hover a table to light up its relations and actions; click one to read the policy that governs it.

Crisper version: assets/studio-map.mp4 — the same run at full resolution. One real run on a sample commerce domain, --gate delete. The locks are not annotations added for the video: they are what the studio draws from your ontology, which is why nine actions carry one and eighteen do not.

Be exact about what that is worth. The relations come from ontology/_links.mjs, which init derives from your Prisma relations, so Customer_list's description reads List Customer records. Relations: has many Order. The agent is told that a Customer has many Orders. It still cannot follow the edge: no traversal tool, no join, no aggregate, and Customer_list refuses a filter that reaches into Order. Knowing the shape of a domain and being able to query across it are different things, and only the first one is here.

Quickstart

Seven steps, every output verbatim from one recorded run. The reasoning behind each one — and the failure each prevents — is in Quickstart, annotated; requirements and the Prisma 7 caveat are the first thing on that page.

1. Install orangerail into the project you are about to scan.

npm i -D orangerail

2. Scan your project, in a repo with a prisma/schema.prisma.

$ npx orangerail init --yes --preset approval-for-writes --no-studio
  ✓  scanned your sources — 2 object(s), 6 action(s)
  ✓  generated a governed MCP server under ontology/
  ✓  --gate delete: 2 of 6 write action(s) gated behind human approval — the other 4 run when the agent calls them
  ✓  recorded that posture in orangerail.governance.json — commit it
  ✓  approvals queue + audit chain at .orangerail/store/ — inside this project, so an
     agent with file tools over this directory can write them

  These files are yours — re-scans never modify them; `orangerail sync` reports drift.

  Change what is gated by editing `policy` in ontology/<action>.mjs, or re-run init
  with `--gate all` (gate every write) or `--gate none` (gate nothing).
  orangerail.governance.json holds the posture init just generated, which nobody has reviewed yet.
  From now on `orangerail sync` fails when an action gets weaker than that file, and
  `orangerail mcp` refuses to serve it. Read the file, then run
  `orangerail sync --accept-governance` to vouch for it as reviewed.

  That store is the record of which writes a human approved, and appending one line to
  .orangerail/store/approvals.jsonl marks a staged action approved — the next
  `check_approval` then executes it, because the gate reads that store and never the
  audit chain. `orangerail audit verify` reports the forgery afterwards; it is a report,
  not a gate, and it does not prevent the write. The generated config carries the
  one-line move at the `createFileStore` call — see docs/audit-log.md.
orangerail docs: wrote /private/tmp/shop/.orangerail/generated/AGENTS.md

Done. Run `orangerail studio` to explore the map, or `orangerail mcp`.

3. Install the runtime the generated code loads.

npm install orangerail-core zod

4. Give the generated actions a database to reach.

npm install @prisma/client@6
export DATABASE_URL="file:./dev.db"
npx prisma generate
npx prisma db push --skip-generate

Already have a database? Do not db push over it — adopting orangerail against an existing database.

5. Point your agent host at it. Drop this in your project root as .mcp.json:

{
  "mcpServers": {
    "orangerail": {
      "type": "stdio",
      "command": "./node_modules/.bin/orangerail",
      "args": ["mcp"],
      "env": { "DATABASE_URL": "file:./dev.db" }
    }
  }
}

Other hosts, the claude mcp add one-liner, and running from source: wire it into your agent host.

6. Record the governance baseline — and commit it. ontology/ is yours to edit, so the one line that disarms the whole flow is one careless deletion away and a re-scan cannot notice. The posture is compared against a recorded file instead.

npx orangerail sync --accept-governance

Commit orangerail.governance.json. Its whole value is that a pull request removing an approval gate shows "approval": "required" turning into null in its own diff, in front of a reviewer, before CI runs at all.

7. Now leave. While you are gone the agent works the queue: the writes you left un-gated go through, and the deletion it was asked for stops. When you come back: