Pi agent · how it works
Pi does the work. Jev guards the shell.
Pi is the agent on Deal Desk's Pi tab. You ask a question in plain words; Pi reads the live deal board, drops in new deals, asks Jev for judgments, and does its arithmetic in Python on a Linux box with no internet. This page explains each part, what you see on screen, and where to check that it really happened.
01At a glance
| Harness | Pi Durable (@earendil-works/pi-durable 1.3), run by the Cloudflare Agents SDK's PiHarness. It keeps the conversation, its pending work and its retries. |
|---|---|
| Where | PiDesk, a SQLite-backed Durable Object in the jev-pi-sandbox Worker. One per session. That Worker has no public URL; Deal Desk reaches it over a service binding. |
| Model | Kimi K2.7 Code (@cf/moonshotai/kimi-k2.7-code) on Workers AI, through Cloudflare AI Gateway jev-gateway. Chosen for the event; one setting swaps it. |
| Hands | A Cloudflare Sandbox: a container attached to the same Durable Object. Alpine Linux with bash, python3 and jq. Internet is off. |
| Guard | The Jev command gate: Jev scores every shell command before it runs, and code blocks the risky ones. |
| Tools | Six: deal_board, deal_drop_item, jev_decide, sandbox_bash, sandbox_write_file, sandbox_read_file. |
02One question, end to end
/workspace by path checks rather than by Jev.- You ask.The Pi tab sends your prompt (up to 2,000 characters) with the id of your latest Agent run to
POST /api/pi/<session>/ask. If you haven't run the Agent yet, the tab starts a run first so Pi has a board to read. - Deal Desk checks you.With a pass, the ask counts against its 10 Pi asks and is refunded if the call fails. Without one, a per-network rate limit applies. Then the request goes over the
PIservice binding tojev-pi-sandbox. - The Durable Object commits it.Your session's
PiDeskhands the prompt to the Pi harness, which writes it to SQLite before any work starts, and answers right away with202 Accepted. - The model plans.The harness sends the conversation, Pi's instructions and the tool list to Kimi K2.7 Code through AI Gateway. The model replies with text, tool calls, or both.
- Tools run, one committed step at a time.Each tool call and its result are saved as they happen. Shell commands pass the Jev gate first. The loop repeats until the model writes a final answer.
- You watch it land.The tab polls
GET /api/pi/<session>/stateabout once a second and draws the transcript and the gate log from what the Durable Object has saved.
03The Durable Object
A Durable Object is a small, single-threaded Cloudflare server with its own SQLite database, addressed by a name. Pi gets one per session: PiDesk, named by your session id. Your browser keeps that id, so a reload, or opening the tab later, brings back the same conversation. New session makes a new id, which means a new Durable Object, an empty transcript and its own sandbox.
The Pi harness stores everything it does in that database: your messages, the model's replies, every tool call and result, and work still pending. That's what "committed before you see it" means. The page only ever shows what is already saved, and a turn that is interrupted, say by a deploy or a restart, resumes from the last saved step instead of starting over. Tools that only read (deal_board, jev_decide, sandbox_read_file) are marked safe to run again during recovery; tools that change something are not.
The same object keeps a desk_gates table with every command the gate has checked, and owns the sandbox container. Nothing about a session lives anywhere else.
04The model
Pi thinks with Kimi K2.7 Code, Moonshot AI's coding model, which Cloudflare hosts on Workers AI. Every call goes through Cloudflare AI Gateway jev-gateway with logging on and the tag app: jev-pi-sandbox, at a low thinking level to keep answers fast.
MODEL) in jev-pi-sandbox, and the harness, tools, gate and transcript stay exactly the same. The model chip at the top of the transcript always shows which model answered.What the model is told: Jev is a decision model that returns probabilities, so report them rather than rounding them into certainty; do arithmetic in Python in the sandbox, never in your head; you can draft emails into /workspace but cannot send anything or contact anyone; lead with a one-sentence recommendation and cite card numbers.
Any model can misread the board or pick a clumsy tool. That's why the checks don't depend on it: Jev returns calibrated probabilities, the maths runs as code, and the gate decides with fixed thresholds.
05The six tools
| Tool | What it does | Reaches | On recovery |
|---|---|---|---|
deal_board | Reads every card on your Agent run: lane, thesis fit, hype, fact or signal confidence, red flag, next action. | Deal Desk API | safe to re-run |
deal_drop_item | Adds a new seller email, teaser or headline to the running Agent and waits for its decision. | Deal Desk API | changes the board |
jev_decide | Asks Jev typed questions (yes/no, pick one, rate) and returns the probabilities. | jev-gateway | safe to re-run |
sandbox_bash | Runs a shell command in the sandbox, after the Jev gate allows it. | Sandbox | runs code |
sandbox_write_file | Writes a text file, such as a Python script or a draft email, inside /workspace. | Sandbox | writes a file |
sandbox_read_file | Reads a text file back from /workspace. | Sandbox | safe to re-run |
The tools that need secrets (the Jev token, the Deal Desk API) run in the Durable Object, never in the container. The sandbox only ever sees the commands and files Pi sends it.
06The Sandbox
Pi's hands are a Cloudflare Sandbox: a Linux container that belongs to the same Durable Object. It starts the first time Pi needs it, on the "lite" container size, from an Alpine Linux image with bash, python3, jq and coreutils.
- No internet. The container starts with internet access turned off, so nothing in it can download code or send data out.
- One folder. Commands start in
/workspace. File reads and writes outside it, or with..in the path, are refused before they reach the container. - Bounded. A command times out after 30 seconds unless Pi asks for more (120 at most), and output past 6,000 characters is cut.
- Short-lived. After 10 minutes without use the container stops. The transcript stays in the Durable Object; files in
/workspacedon't survive a stop.
The transcript's top row shows whether your sandbox is running or stopped.
07The Jev command gate
Before any sandbox_bash command runs, the Durable Object sends it to Jev with one question in plain words: a coding agent wants to run this command inside an isolated Linux sandbox with no internet; working directory /workspace. Jev answers three typed questions in a single call, and code applies fixed thresholds:
Safe (reads, prints, computes, writes inside /workspace), risky (outside /workspace, installs, long jobs) or destructive (deletes broadly, kills processes, tampers with the system).
blocked at destructive ≥ 50%Does the command download code from the network and run it?
blocked at ≥ 70%Does the command try to send files or secrets off the machine?
blocked at ≥ 70%A blocked command never reaches the container. Pi gets back JEV GATE blocked: destructive 92%. The command was not run. (with the real figure) and is told to say so and pick a safer command. A command that passes runs, and its result starts with the gate's reading, for example JEV GATE passed (safe 97% · remote_exec 2% · exfiltration 1%, 240 ms).
rm -rf /workspace/*
expected: blocked · destructive
The "Test the gate" prompt on the Pi tab asks Pi to run exactly this, so you can watch the gate refuse it and read Jev's probabilities.
Every check, allowed or not, is written to the Durable Object's desk_gates table. The Jev command gate card shows the last ten: the command, ran or blocked, and the probabilities behind it. These calls reach jev-gateway as consumer jev-pi-sandbox-gate; Pi's own jev_decide calls are jev-pi-sandbox-tool.
The gate covers shell commands. File writes don't go through Jev; they are confined to /workspace by the path check, and the container has no network either way.
08Reading the transcript
The transcript is the Durable Object's saved conversation, drawn in order. The chips above it show your session id, the model that answered, and whether the sandbox is running.
Your prompt. The run id Pi was given is hidden from the display.
The tool's name and its arguments, then its result folded under result. Shell calls carry a Jev gate chip: passed, with the probabilities, or blocked.
The model's text between tool calls, labelled with the model's name.
The last message once Pi is done, outlined in ink. It should lead with a recommendation and cite cards as #n.
A red box when the model call itself failed, with the error. The saved steps before it stay.
While Pi works you'll see Pi is working… at the bottom. New rows fade in as they are committed; nothing appears that the Durable Object hasn't saved.
09Proof in Cloudflare
Every step leaves a record you can check outside the page:
- Workers Logs and traces for
jev-pi-deal-desk(the ask, with your pass id) andjev-pi-sandbox(the Durable Object, the container, the service-binding calls). - AI Gateway
jev-gatewaylogs: each model call (taggedapp: jev-pi-sandbox) and each Jev call, by consumer. - D1
jev-gateway-audit: one row per Jev call, gate checks included, with status, latency and tokens. - The gate log in the Durable Object, which is what the gate card shows.
10Limits
- Pi can draft an email into
/workspace; it cannot send one, or contact anyone. - The sandbox has no internet: no package installs, no web lookups.
- The model is there for the demo. Read its answer next to the board and the probabilities it cites.
- Prompts are capped at 2,000 characters. A pass includes 10 Pi asks.
- All companies on the board are fictional sample data.
11Try it
Each prompt on the Pi tab shows a different part:
deal_board and cites the cards and probabilities behind its pick.
Check the mathsWrites a Python script with sandbox_write_file and runs it with sandbox_bash, through the gate.
Drop in a dealSends a new teaser to the running Agent with deal_drop_item and reports where it landed.
Draft an introWrites an email to /workspace/intro.md and says it hasn't been sent.
Test the gateAsks for rm -rf /workspace/* so you can watch Jev and the thresholds refuse it.
Sources: jev-pi-sandbox/src/index.ts, its wrangler.jsonc and Dockerfile, and the Deal Desk Worker's /api/pi routes.