How to deploy 100% deterministic AI agents on ScramDB
Your agent runs inside the database on a deterministic execution runtime: same input, same output, every run.
We made AI agents 100% deterministic on ScramDB. Give an agent the same input twice and you get the same output twice, on your laptop or on a powerful server.
The agent runs inside the database, where it asks the model once for each request and saves the answer in the row. From there it decides with code that always gives the same result, so you can replay any decision later.
The rest of this post is us deploying one, step by step, and you can follow along on your own machine.
Same input. Same output. Every run.
For a team that runs agents on real customer data this means:
- An audit trail. Every decision points to the exact version of the agent that made it.
- Replay. Pick any day in the past and you get the decisions of that day again.
- A closed agent. It can call the one service you allowed. It can't read files, or data you kept from it.
- Rules the database enforces. What an agent can see, change and call is checked by the database, for any agent framework.
- One system. The runtime, the sandbox, the policies and the data are in the same database.
Why it is 100% deterministic
An agent has a model in it, and a model won't give you the same answer every time you ask. We can't change that, so we ask only once. On ScramDB the agent asks the model once for each request and saves the answer in the row of that request.
Everything after that is code, and the code runs inside the database on our fully deterministic runtime, afterburner. It's built into the engine and it's always deterministic, there is no setting for it:
- No clock, no randomness, no hidden state. The code can read its arguments and that's it.
- Sealed. It can't reach the network, the filesystem or the environment.
- Identical on every CPU. NaN values are canonical and a module has no threads, so two machines produce the same floats in the same order.
- Fuel. Each run has a budget counted in instructions, so a loop that never ends is stopped at the same instruction on every machine.
The code can be JavaScript, TypeScript, Python, Ruby, Rust, Go, C or C++, and whichever you pick runs in the same sandbox under the same rules.
So a request has one answer, the answer is saved, and any decision made from it can be made again.
How the sandbox isolates it
The sandbox is also what keeps the agent isolated, because code that runs in the database only has the memory it was given and can't see the database's own memory, other functions or the machine underneath. Anything from outside has to be allowed in the package's grant, and this is a grant that allows nothing:
{
"fs": "None",
"net": "None",
"env": "None",
"crypto": false,
"child_process": false,
"allow_exit": false,
"http_timeout_ms": null,
"listen": "None"
}
Every package has a grant, so you can read what a package can touch before you install it. A function called from SQL is always sealed, whatever its grant says. Even when a package asks for the network, a function from that package gets no socket. You can check this in scram_functions, where caps is sealed for every function:
SELECT name, language, caps FROM scram_functions;
A function also can't open a connection or run its own queries. It gets the rows the statement gives it and returns an answer, and SQL decides what happens with the answer, under the role that ran the statement.
If a function uses too much, only that call fails. A call that runs out of fuel just ends, a call that asks for more memory than its limit gets a failed allocation inside the sandbox while the server keeps running, and a call that returns too much output is refused. One bad agent can't take the database down. A C extension loaded into the server process can do that with one bug.
The part of an agent that calls a model is packaged differently, as a server the database keeps running, and it gets exactly the access its grant lists, which you'll see in step 1.
Deploy an agent
There are seven steps. The example agent works on a shop's refund requests and asks Claude about each one.
CREATE TABLE refund_requests (
id int PRIMARY KEY,
amount_cents int NOT NULL,
days_since_order int NOT NULL,
prior_refunds int NOT NULL,
note text NOT NULL,
model_verdict text,
model_reason text,
decision text
);
INSERT INTO refund_requests (id, amount_cents, days_since_order, prior_refunds, note) VALUES
(1, 1900, 3, 0, 'Arrived with a cracked screen, photo attached.'),
(2, 24900, 12, 1, 'Works fine, I just found it cheaper elsewhere.'),
(3, 4500, 41, 0, 'Never opened it, forgot to send it back in time.'),
(4, 900, 2, 5, 'Wrong colour again.');
1. Write the agent
We build the agent as a package with burn (install it with curl -fsSL https://afterburner.sh | sh), and the Claude client it uses is a package in burn's registry:
burn init ./refund_agent --namespace acme --name refund_agent
cd refund_agent
burn add burn/anthropic
This agent is JavaScript, but you can write an agent in any programming language our deterministic execution runtime supports. It reads the requests that have no verdict, asks Claude about each one and saves the verdict in the row:
// source/main.js
const http = require("http");
const { Client } = require("pg");
const claude = require("burn/anthropic");
const VERDICT = {
type: "json_schema",
schema: {
type: "object",
properties: {
verdict: { type: "string", enum: ["approve", "deny", "escalate"] },
reason: { type: "string" },
},
required: ["verdict", "reason"],
additionalProperties: false,
},
};
async function judge(request) {
const out = await claude({
model: "claude-opus-5-5",
max_tokens: 2048,
system: "You review refund requests for a shop. Decide approve, deny or escalate, and give the reason in one sentence.",
prompt: JSON.stringify(request),
output_config: { effort: "low", format: VERDICT },
});
// A refusal or a cut-off answer is not a verdict, so a person gets it.
if (out.stop_reason !== "end_turn") return { verdict: "escalate", reason: "no verdict: " + out.stop_reason };
return JSON.parse(out.text);
}
async function run() {
const db = new Client({
host: "127.0.0.1", port: 5432, database: "agent_refunds",
user: "agent_refunds", password: process.env.REFUND_AGENT_TOKEN,
});
await db.connect();
const open = await db.query(
"SELECT id, amount_cents, days_since_order, prior_refunds, note FROM refund_requests WHERE model_verdict IS NULL");
for (const request of open.rows) {
const { verdict, reason } = await judge(request);
await db.query(
"UPDATE refund_requests SET model_verdict = $1, model_reason = $2 WHERE id = $3",
[verdict, reason, request.id]);
}
await db.query(
"UPDATE refund_requests SET decision = refund_decision(amount_cents, prior_refunds, model_verdict) WHERE decision IS NULL");
await db.end();
return open.rows.length;
}
http.createServer((req, res) => {
run().then(
(n) => res.end(`judged ${n} requests\n`),
(err) => { res.statusCode = 500; res.end(err.message + "\n"); });
}).listen(9200);
The query has WHERE model_verdict IS NULL, so each request is sent to the model one time, and from then on its verdict is a column in the row.
afb.toml lists the dependencies and tells the database to keep the package running:
# afb.toml
[package]
name = "refund_agent"
namespace = "acme"
version = "0.1.0"
language = "js"
entry = "source/main.js"
[dependencies]
"burn/anthropic" = "sha256:53ff553dea9c7565ba65c1b03a5ed0611cc47179b351192fe709a834c229d4bb"
[npm]
pg = "8.13.1"
[metadata.daemon]
autostart = true
manifold.json is the grant. This agent can reach Claude's API and the database, read two environment variables and listen on one port:
{
"fs": "None",
"net": { "OutboundFull": ["api.anthropic.com", "127.0.0.1:5432"] },
"env": { "AllowList": ["ANTHROPIC_API_KEY", "REFUND_AGENT_TOKEN"] },
"crypto": true,
"child_process": false,
"allow_exit": false,
"http_timeout_ms": 30000,
"listen": { "Ports": [9200] }
}
It can't reach any other host, file or variable. The server has its own list as well, so add ANTHROPIC_API_KEY and REFUND_AGENT_TOKEN to env_allowlist under [udf.daemon] in the server config (keep the names that are already there) and set both variables where the server runs.
2. Write its rules
We treat Claude's verdict as a suggestion and let the shop's own rules decide what happens. Those rules are a function in the database, which you can paste into SQL without a build:
CREATE FUNCTION refund_decision(amount_cents int, prior_refunds int, model_verdict text)
RETURNS text LANGUAGE js AS $$
module.exports = (batch) => {
const { amount_cents, prior_refunds, model_verdict } = batch.columns;
const n = batch.row_count;
const decision = new Array(n);
for (let i = 0; i < n; i++) {
const needsAPerson = amount_cents[i] > 5000 || prior_refunds[i] >= 3;
decision[i] = model_verdict[i] === 'approve' && needsAPerson ? 'escalate' : model_verdict[i];
}
return { row_count: n, columns: { decision } };
};
$$;
With this rule an approval above 50.00, or for a customer who already has three refunds, goes to a person. The function is sealed and deterministic, so one verdict on one row always gives the same decision.
The function gets a batch of rows and returns a batch, so the database calls into the sandbox once per batch and not once per row. That keeps it fast.
3. A branch and a token
The agent works on its own branch of the database, not on production. One statement creates the branch, the role, the storage quota and the rows the agent can't see:
CREATE AGENT refunds WITH (
clone_from = 'scramdb',
quota_bytes = '1 GB',
exclude = 'public.refund_requests WHERE amount_cents > 100000'
);
CREATE AGENT TOKEN FOR refunds VALID FOR '1 day'; -- shown once
Creating the branch copies no data, so it's ready immediately, also for a very large database. The role is agent_refunds. It can connect only to its own branch and it can't create tokens. The agent logs in with the token, so put it in REFUND_AGENT_TOKEN.
4. Set its policies
Policies control what the agent can see and do on its branch. They are not prompts. The database checks them when a row is read or written, so neither the agent nor the model can get around them.
- What it sees.
excludehides a table (exclude = 'public.salaries') or the rows that match a condition. The statement above hides refunds over 1,000.00. This uses row level security on the branch only, so other roles keep their access. Since the agent can't read those rows, they never reach the model either. - How much it writes.
quota_byteslimits the size of the branch. When the branch reaches it, statements that would grow it are refused.DELETEstill works, so the agent can free space. - How it gets in. The only way in for the agent is its token, which is stored as a salted hash and expires after the time you set.
DROP AGENT TOKENS FOR refunds;cancels all of its tokens. - What it can't do. If the agent tries to approve a merge, apply one or create a token, the database answers permission denied. A merge that deletes a large share of a table is also refused unless a person adds
ALLOW DESTRUCTIVE.
The agent's role is a normal database role, so you can restrict it further with GRANT on single columns and with CREATE POLICY (USING and WITH CHECK) on single rows.
5. Install it and run it
Build the package. You don't need to publish it:
burn install
burn package # writes ./acme-refund_agent-0.1.0.afb
The .afb file is the whole agent. Its identity is the SHA-256 of the file, and the build is reproducible, so the same inputs give the same bytes on any machine. You install it by sending the file's bytes to the database from any client, for example from Python:
import psycopg
afb = open("acme-refund_agent-0.1.0.afb", "rb").read()
with psycopg.connect("postgresql://scramdb@localhost:5432/scramdb") as conn:
digest = conn.execute("SELECT scram.install(%s)", (afb,)).fetchone()[0]
print(digest)
ScramDB reads the package name from the file, checks it, returns the digest and starts the agent. The install doesn't use the registry or the internet, so it also works on an air-gapped machine, and it has to be done by a superuser. To check that the agent is running:
SELECT package, state, ports, digest FROM scram_daemons;
Start a run and look at the result:
curl -X POST http://127.0.0.1:9200/run
-- connected to agent_refunds
SELECT id, model_verdict, decision FROM refund_requests ORDER BY id;
A run looks like this:
id | model_verdict | decision
----+---------------+----------
1 | approve | approve
2 | deny | deny
3 | escalate | escalate
4 | approve | escalate
Claude approved request 4, since it's only 9.00, but the customer already had five refunds, so the rule sent it to a person.
Start the run a second time and the result is the same. Each request already has its verdict by then, so the agent has no reason to call the model, and the rule returns the same decision for the same row.
The agent reads the live table. There is no export, no pipeline and no copy, so a request that was just filed is included.
6. Put a budget on it
Both parts of the agent have limits. The rule uses the server's limits for functions:
[udf]
fuel_per_batch = 50000000 # instructions, not milliseconds
memory_bytes = 268435456
timeout_ms = 1000
output_bytes = 16777216
Fuel counts instructions and not time, so a function hits the limit at the same point on a laptop and on a busy server. A rule that passes in CI isn't stopped in production because another query is using the CPU.
For the agent, max_tokens in the code limits each call to Claude, http_timeout_ms in the grant limits how long a call can take, and the branch quota limits what it writes.
7. Let a person merge it
Everything the agent wrote is still on its branch, and since it isn't allowed to merge into production, it sends a merge request instead:
-- the agent, connected to its branch
REQUEST MERGE OF DATABASE agent_refunds;
-- you
APPROVE MERGE REQUEST 'mr-...'; -- answers a one-time token
APPLY MERGE REQUEST 'mr-...' USING TOKEN '<approval_token>';
The request returns a preview for each table, with sample rows before and after the merge. You approve it or you don't. If the agent changes the branch after your approval, the apply is refused and the agent has to send a new request, so only what you reviewed is merged.
You can also take a merge back later:
UNDO MERGE REQUEST 'mr-...';
This removes what that merge wrote and keeps all later writes.
Ship it like software
The agent is one file with one hash and the rule is one statement, so you release changes to them like any other software.
8. Update it
To change the prompt, the model or anything else in the agent, edit the code, set version in afb.toml to 0.2.0, build, and install the new file the same way:
burn package # writes ./acme-refund_agent-0.2.0.afb
Installing replaces the old package under the same name. The database stops the running agent and starts the new one. Installing the same file again does nothing. The rule changes with a normal CREATE OR REPLACE FUNCTION.
The new agent has a new digest, and scram_modules shows which digest is installed. To roll back, install the old file again, so keep your .afb files.
A team that shares agents can use a registry: burn publish uploads the file and SELECT scram.install('acme/refund_agent@0.2.0'); installs it by name.
When someone asks which agent made a decision, with which prompt and which model, you give them the hash. The same hash and the same data give the same decisions.
Govern it where the data is
An agent reads sensitive data, calls services and acts for people. On ScramDB all three are controlled in the database, which means the rules apply to every agent, whatever it was built with and wherever it runs.
- Sensitive data. The policies in step 4 cover it: excluded tables and rows, column grants and row policies. The database checks them on every read.
- Acting for your users. When an agent answers questions for your users through the built-in MCP server, each request uses that user's credentials and runs as that user's role. Two users with the same question get the rows their own policies allow.
- Calling services. The grant in step 1 lists every host the agent can call, and this agent can call
api.anthropic.com. The rule function can't call anything. - Any client. The checks are in the database and not in a client library. They apply to an agent that connects with a PostgreSQL driver, through MCP, or to any node of a cluster.
- Records.
SHOW MERGE REQUESTSlists every request and its status.scram_branch_mergesrecords what each merge changed in each table.scram_daemonsshows the agents that are running, andscram_modulesthe digest of the installed code.
Replay any run
Suppose a customer complains three weeks later about a refund that was denied. You can look at what the agent did on that day:
CREATE DATABASE refunds_replay FROM scramdb AT TIMESTAMP '2026-11-14T09:30:00Z';
This creates a branch with the database as it was at that time (it needs a base backup and WAL history). The branch has the model's verdict for the request and the reason it gave. Run the rule from that day on it and you get the same decisions, row for row. Because the model isn't called again, there is nothing that could change the result.
You won't get this feature from an agent that lives in a separate process and calls four other services.
Worth knowing
- The model. The example uses Claude with
burn/anthropic. The registry also hasburn/openaiandburn/gemini. - Types. A function takes booleans, integers,
real,double precision,text,date,timestamp,byteaandjsonb. Castnumericanduuidtotextaround the call. - Languages. You can write your agent in any language the deterministic execution runtime supports: JavaScript, TypeScript, Python, Ruby, Rust, Go, C and C++. You can paste a rule inline in
js,ts,pythonandruby, and every language can be built as a package. The part that calls the model, likemain.jsabove, has to be JavaScript or TypeScript today. - Installing. Only a superuser can install a package, so an agent can't replace its own code.
- Sealed functions. A function called from SQL is sealed even if its package asks for the network.
Run it on your own data
All of this is in ScramDB today, so you don't need a separate agent runtime, sandbox service or policy engine. Start in a few minutes, or talk to us about ScramDB Cloud and running deterministic agents on your workload.
The docs have the details: Program your Database, Branching for agents and Install and use a package. Your agent can read them as well, because every docs page is available as plain text and https://scramdb.com/llms.txt lists them all.


