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.
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:
- Block, approve and allow a deleteThen try to cheat it, and share the run as a link.
- Edit a rule and watch the fingerprintReword it and the fingerprint holds still. Change what is required and it moves.
- Check a signed receiptChange one character and the signature fails.
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.
- Temporal and Argo Workflows.They run your steps, retry them and resume after a crash. Joltrin does not run anything. Use a workflow engine to execute work, and Joltrin when an agent chooses its own steps and something must say "not yet, the backup is missing". They can be used together.
- OPA, Gatekeeper, Kyverno and Cedar.Mature, widely used policy engines that answer who may do what. Joltrin answers "did the earlier steps happen", and it keeps the trace and the agent-readable refusal built in. Use a policy engine for authorization.
- Where Joltrin fits better.The rule is about order, the caller is an AI agent over MCP or A2A, and you want it embedded in a Go program with no extra server.
- Where it does not.It is a young project. The Kubernetes gate is one replica with in-memory state. If you need audited, high-availability enforcement today, use the established tools.
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
- Private IntentDesign, threat model and limits.
- Barrier test resultsRuns with real agents, what they show, and what they do not.
- Agent protocolsMCP, A2A, memory, and your own runbooks.
- Kubernetes admission gateThe barrier in front of kubectl delete, with manifests and limits.
- Verification engineHow the check works and what it is not.
- Getting startedFrom downloading it to building your first program.
- AI examplesGemma over Ollama, LangGraph over MCP, and Hugging Face search.
- ExamplesRunnable examples, starting with a quickstart.
- Live demosThe three browser experiences.
- What is JoltrinThe storage engine in plain words.
- Why JoltrinThe problem, the approach, and where it is not the right tool.
- ArchitectureA technical whitepaper on the engine.
- ScalabilityCapacity and limits.
- Operations and failoverRunning it and handling failures.
- Data Manager and toolsThe server and the visual tools.
- Azure deploymentDeploying it on Azure.
- BenchmarksNumbers, how to reproduce them, and their limits.
- Roadmap and platform supportWhat is planned and what is supported.
- Who it is forWhether it fits your team.
- Investor notesWhat has and has not been proven.