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/ .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:

$ npx orangerail status

orangerail status objects: 2 actions: 2 approval-gated, 4 auto baseline: 6 action(s) match orangerail.governance.json preset: approval-for-writes pending: 1 approval(s) awaiting a decision store: /private/tmp/shop/.orangerail/store Inside the project root, so an agent with file tools over this directory can write it: one appended line in approvals.jsonl is a decision no human made, and the next check_approval executes the staged action — the gate reads this store, never the audit chain. orangerail audit verify reports the forgery afterwards; it is a report, not a gate. Pointing the store dir at a directory this agent's process cannot write is what removes the reach — see docs/audit-log.md. server: not detected — no orangerail mcp is running against this store hosts: .mcp.json declares orangerail and nothing else. Project scope only (.mcp.json, .cursor/mcp.json, .vscode/mcp.json); user- and machine-scope MCP config is not read. audit: chain OK — 5 record(s) verified

$ npx orangerail approvals list c4818df5-770c-446f-883a-e9c0f7e615a2 "deleteCustomer" by "local-dev" [dev] 0s ago input={"id":2}

1 pending approval(s).

$ npx orangerail approvals approve c4818df5-770c-446f-883a-e9c0f7e615a2 approve ok (approved)

The agent's next check_approval is the first moment the row can change. Nothing ran before you said so, and every step is on the hash chain. That whole sequence is what tests/e2e/ONT-093-quickstart-runs-as-documented.sh runs against this repository's own build on every regression pass.

Why the prompt is the wrong control

The thing stopping you from walking away is not that the agent does too much. It is that your only control is a question it has to ask you. The twentieth prompt of the afternoon gets the same click as the first, and the switch that ends the asking ships in the box — Claude Code's bypassPermissions mode "skips permission prompts, except those forced by explicit ask rules", per its own permissions reference. A boundary re-established by a person on every call cannot hold once nobody is there.

The prompt is also the wrong *shape*. It asks about a tool — may this run Bash — and the risk you carry is about your domain: stock edits are fine, order deletions are not, refunds under $50 need nobody. That distinction does not exist at the tool level. It exists in your schema.

The run this is built for

![a back-office queue handed to an agent with nobody watching: ordinary writes finish, a deletion stops and becomes an approval, and the one declared line that stopped it](./examples/unattended-que