Joltrin

Documentation

Joltrin checks an AI agent's action against the recorded trace before it commits, independent of what the agent claims. This page is a path from the idea to a working integration.

Not sure where to start? Pick the line that sounds like you.

I build with Go.Run the barrier example without cloning the repository.Run the local demo I run AI agents and want a guardrail.One command installs it for the agents on your machine.Go to section 5 Show me before I install anything.Try to drop a database in your browser and watch the barrier refuse.Open the live demo I want agents to follow my rules.Your own rules, signed approvals and a receipt for each allowed action.Go to section 9 I run Kubernetes.The same check can sit in front of kubectl as an admission webhook.Go to section 7 I am deciding if this fits my team.Who it is for, and who it is not for.Read it on GitHub

1. What it protects against

An agent can propose a destructive action and report success from its own context. If the same agent also decides the action is safe, both judgments can fail for the same reason. The danger in production is that correlated failure.

2. The independent verifier model

The agent emits intent. The verifier checks that intent against the steps the server has recorded and the runbook's preconditions and safety rules. It does not use the agent's claims, prompt context, self-evaluation or confidence. The check and the commit are one call, so a step is recorded only if it passed, and a step whose required state is missing is refused. A claim that something happened is not evidence that it happened.

3. The blocked-result payload

A blocked call returns a normal result with fields the agent can act on:

{
  "blocked_by": "precondition",
  "missing_state": "backup_validated",
  "established_by_steps": ["validate_backup"]
}

Treat it as a replan signal, not a reason to retry. For a production database drop, the safe order is:

drop_prod_db      blocked, backup_validated is missing
validate_backup   blocked, backup_taken is missing
take_backup       allowed
validate_backup   allowed
drop_prod_db      allowed

Repeated blocks add attempts and next, which says whether to run the establishing steps or stop and ask. With memory turned on, the server also counts which rules block runs and how often agents recover.

4. Five-minute local demo

You need Go and a terminal. No clone, API key, or running database is required. The first run downloads dependencies and compiles the example.

go run github.com/sharedcode/joltrin/v5/examples/verify_barrier@latest

What success looks like: the first drop_prod_db is BLOCKED. The example records the backup steps and retries; the final drop is committed. No real database is changed. The example records sample steps with the real verifier.

If you see go: command not found, Install Go and reopen your terminal. If dependency downloads fail, check your network and Go proxy settings. An older Go may download the required toolchain; restricted environments may need it installed first.

Next, connect an MCP agent or read the Go example source to adapt the runbook. Or try the barrier in your browser.

5. MCP integration

On macOS or Linux, this installs the server, checks its checksum, and registers it with Claude Code, Codex, and Gemini CLI, whichever are installed. No Go needed. Review the install script before running it:

curl -fsSL https://raw.githubusercontent.com/SharedCode/joltrin/master/scripts/install.sh | sh

On Windows, in PowerShell (review the script):

irm https://raw.githubusercontent.com/SharedCode/joltrin/master/scripts/install.ps1 | iex

Or in Command Prompt (cmd.exe):

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/SharedCode/joltrin/master/scripts/install.ps1 | iex"

Restart your agent after installation. Ask it: “Use the joltrin tools to run drop_prod_db on workflow db-maintenance with trace id first-run.” Expect a block naming backup_validated, then ask it to run the missing steps and retry in the same trace. The sample tools do not change a real database.

If the tools are missing, check the installer's registration output and your agent's MCP configuration. For manual installation or an agent that was not registered automatically, follow the setup guide below.

Building with Go, Windows, your own runbooks, and memory are covered in the README and Agent protocols.

6. A2A integration

The same check gates an A2A agent. A blocked step moves the task to input-required with the same fields. See Agent protocols.

7. Kubernetes admission gate

The same check can sit in front of cluster operations. sop-k8s-gate is a validating admission webhook. A policy file maps an operation to a runbook step, and the API server refuses the operation until the steps it depends on are recorded for the trace named in the object's joltrin.dev/trace-id annotation:

$ kubectl -n prod delete pvc orders-db-data
Error from server: admission webhook "gate.joltrin.dev" denied the request:
  step "drop_prod_db" requires state "backup_validated",
  which has not been established in this trace

Steps are recorded with POST /commit and a bearer token. Give the token to the job that takes the backup, not to the workload being controlled, because anyone who holds it can record a step. --warn-only allows every request and reports what would have been blocked, so you can try a policy first. It runs as one replica and keeps recorded steps in memory. See Kubernetes admission gate for the manifests, what was checked, and what it does not do.

8. AI in how Joltrin is built and run

AI tools show up in three places in this project. Each one has a check around it.

Code review. Every pull request to master gets an automated review from Gemini and one from Claude. The Gemini review is a required status on the exact commit being merged, so a change cannot land until it passes. A comment on a pull request can ask either bot for a suggested fix. Suggestions are only proposed, and nothing is pushed without a person.

Models in the product. The built-in assistant calls Gemini or OpenAI with native tool calls. For a fully local setup, the gemma_ollama example runs Gemma 3 through Ollama and embeds context with embeddinggemma. The barrier checks each action the model proposes, and each accepted action is committed in its own transaction.

Agent automation. Agents reach the barrier over MCP or A2A. The langgraph_agent example is a LangGraph graph that gets blocked on drop_prod_db, reads the fields in the block, and recovers. The hf_grounded_search example uses Hugging Face embeddings for search.

Replaying decisions before a change ships. ai/replay re-runs the barrier decisions recorded in a past run against a changed workflow. It runs offline, so no tool call executes again, and it lists each step whose allow or block outcome changes.

Testing without a live model. The Gemma example's tests run against a scripted Ollama server, the real vector store, and the real barrier. The test against gemma3:4b runs only when JOLTRIN_OLLAMA_LIVE=1 is set.

Joltrin does not train models, and it does not ship a model registry or drift monitoring. The examples are in examples/README.md.

9. Private Intent

The barrier answers whether the earlier steps happened. Private Intent answers whether the person who owns the system said this agent may do this, and keeps that person's wording out of what anyone else sees.

You write a rule that names the agent, the tool, the resource and what must be true first, such as a validated backup and the owner's approval. Other systems sign the proof: the backup system signs that the backup exists, and a named person signs an approval for one exact action. The agent cannot sign either. When everything is in place the engine signs a receipt for that action and policy, and the system that holds the credentials runs the action only with a valid, unused receipt.

You can try each part in the browser, with a real engine compiled to WebAssembly and nothing sent anywhere:

To run it with an MCP agent on your own machine, clone the repository and use the example: go run ./examples/private_intent demo for a scripted run, or init, attest and approve to wire it to your client. The example gives the agent one tool, delete_database, and the delete is simulated.

What it does not do: it cannot stop an agent that has its own route to the target system, because it only protects actions that run through the executor's check. A receipt shows that a decision was made, not that the action ran. Your wording is sealed on disk and kept out of decisions and receipts, but your machine and the engine still see it, so this is data minimization and not a zero-knowledge system. Shared team rules and approval routing are planned and set up with design partners. They are not built as a product yet.

10. How it compares

Joltrin does one thing: it refuses a step until the steps before it are recorded. Other tools do nearby jobs well, and some of them are the better choice. This is the short version. The full page lists Joltrin's weaknesses too.

Read the full comparison. It describes other projects from their documentation, not from tests run here.

Limits

The barrier only answers, so whatever performs the action must wait for it. It cannot see facts the trace does not contain. A backup in another cloud account has to be represented by a step you trust, such as one that checks that account and records the result. The browser demos run the real checks against stub tools. A hosted instance of the Joltrin server, which handles the site's billing requests, runs on Azure Container Apps with a health check and alerts. The barrier itself is not run as a hosted service. No customers or third-party benchmarks are claimed. Hosting the barrier as a remote service is assessed in the hosting assessment and is not built.

Reference