perch

Portable Durable Objects

The object
is a file.

A portable durable object is one SQLite file holding a Cloudflare-style Durable Object’s data and its code. Copy the file and you have copied the object: its code history, its schema, its next alarm, its rows.

Quick start Read the format

todo.perch 53 51 4c 69 74 65 20 66 6f 72 6d 61 74 20 33 00
  • _obj_meta name, class, live check-in
  • _obj_blobs code, content-addressed
  • _obj_checkins code history
  • _obj_migrations forward-only schema
  • _obj_kv ctx.storage.get / put
  • _obj_alarms the next alarm
  • _obj_changes a changeset per write
  • object code stops here
  • todos id, title, done, created_at, done_at
  • todos_done index (done, done_at)
The to-do example after its first migration. The hatched red rows are the runtime’s half; the green rows are yours, reached through ctx.storage.sql.

The runtime

Open the file, run the class.

The perch binary loads the live check-in’s code into V8 and runs it single-threaded, one event per SQLite transaction. Every write is recorded as a session changeset in the same transaction. The class is an ordinary Durable Object: it extends DurableObject from cloudflare:workers.

A SQLite authorizer draws the line. Object code reads and writes its own tables and nothing else: no _obj_ tables, no DDL, no transactions, no ATTACH, no pragmas that change anything. Schema changes arrive only as migrations.

What object code gets today
public/static files served before fetch() without waking the object (Cloudflare Static Assets rules)
fetch(request)every other HTTP request; import page from "./page.html" for templates
public methodsRPC, also POST /.perch/rpc/<method> with a JSON array of args
ctx.storage.sql.execcursor with toArray, one, raw, rowsWritten
ctx.storage.get / put / delete / listthe KV half
setAlarm / getAlarm / deleteAlarm, alarm()fired on schedule by perch run
transactionSync, blockConcurrencyWhileatomic writes, guarded startup

Refused when object code tries them, from the end-to-end test:

✕ SELECT * FROM _obj_meta
✕ UPDATE _obj_checkins SET message = 'x'
✕ DROP TABLE todos
✕ CREATE TABLE sneaky (id TEXT PRIMARY KEY)
✕ BEGIN
✕ ATTACH DATABASE '/tmp/x.db' AS x
✕ PRAGMA journal_mode = DELETE

The MCP loop

Agents build objects through 13 tools.

perch mcp todo.perch speaks MCP over stdio. An agent changes the object on a preview copy of the file, live data included, tries it there, then releases. The end-to-end test builds the to-do example this way, starting from an empty class.

  1. 1 describe_object what is here
  2. 2 read_code what runs
  3. 3 propose_change code + migrations, on a preview copy
  4. 4 test_call try it, see the rows it touched
  5. 5 release_change one transaction, live moves

rollback_code moves the live check-in back. It moves code only, and it refuses when the old code no longer fits the schema (say, a column it reads was renamed).

describe_objectread

Name, class, live check-in, tables with columns and row counts, files, next alarm, preview state. Start here.

read_coderead

Files at the live check-in, the preview, or any check-in id (a 4+ character prefix works). Binary files come back as base64.

list_checkinsread

History, newest first, with the migrations each check-in added. Unified diffs on request.

query_dataread

Read-only SQL over the object’s own tables, live or preview. At most 500 rows.

propose_changedestructive

Changes the preview copy only. Whole files, exact-string edits and new migrations, applied to a preview copy of the file (live data included), built there, stored tests run. Proposals stack; restart starts over from live.

test_calldestructive

A write call on the preview copy: POST, PUT, PATCH or DELETE to fetch(), an RPC method, or alarm(). Returns the result, console logs and the rows each table gained, changed or lost.

read_objectread

A read of live or the preview: GET or HEAD to fetch() or public/, or an RPC method. The runtime refuses any write made during it and saves nothing.

run_testsread

Runs the object’s test/*.ts files. Each test gets its own fresh, empty copy of the object and a clock it controls.

list_changesread

Recent data changes on live: the event, the time, rows per table, and whether each can be undone.

undo_changesdestructive

Reverses a data change and every newer one in one transaction. Refused across a migration. Recorded, so an undo can be undone.

release_changedestructive

Runs the preview’s migrations on the live file and moves live to its code, squashed into one check-in, in one transaction. Refused if the preview did not build, a stored test fails, or live moved.

rollback_codedestructive

Moves live back to an earlier check-in. Code only, never schema: refused when that code no longer fits the tables.

call_objectdestructive

A write call on the live object: POST, PUT, PATCH or DELETE to fetch(), or an RPC method.

Carry it

Three ways out.

Open it in a browser

The same file runs in a tab, with no install and no server. SQLite runs as WebAssembly, the object's class runs on the browser's own engine, and a service worker hands the app's requests to it. Nothing is uploaded, and the file you download opens in native perch.

Run an object in your browser

Copy the file

Each event folds the WAL back into the main file after it commits, so a plain copy is the whole object. Run the copy anywhere and it serves the same check-in and the same rows.

$ cp todo.perch ~/elsewhere/
$ perch run ~/elsewhere/todo.perch

Export to Cloudflare

perch export writes a Wrangler project. The class source is copied byte for byte; a generated wrapper applies the migrations once and gives the same HTTP surface as perch run, including POST /.perch/rpc/<method>.

$ perch export todo.perch out/
$ cd out && bunx wrangler deploy
The same 17 HTTP calls pass on perch run and on Cloudflare
  1. RPC stats
  2. POST /todos returns a UUIDv7 row
  3. POST without a title is a 400
  4. PATCH marks done
  5. GET ?done=1 lists it
  6. unknown path is a 404
  7. RPC add
  8. RPC stats sees both
  9. constructor is not RPC
  10. alarm fired and removed the done items
  11. DELETE /todos/:id
  12. GET / serves public/index.html
  13. /index.html redirects to /
  14. GET /app.css is text/css
  15. GET /logo.png returns the PNG bytes
  16. revalidating with the ETag gets a 304
  17. GET /stats renders the imported template

Quick start

From a checkout.

perch is a single Rust binary. Build it, make an object, serve it, then hand the same file to your agent.

Every command is listed in /llms.txt, along with the file format and the tool schemas, for agents.

# build
$ cd perch && cargo build --release
$ export PATH="$PWD/target/release:$PATH"

# a blank object, shaped by an agent over MCP
$ perch new hello.perch
$ claude mcp add hello -- perch mcp hello.perch
$ perch run hello.perch

# or import a directory with src/ and migrations/
$ perch new todo.perch --from examples/todo
$ perch call todo.perch add '["buy milk"]'
$ perch fetch todo.perch /todos

# give it to an agent (Claude Code shown)
$ claude mcp add todo -- perch mcp todo.perch

# look inside
$ perch describe todo.perch
$ perch checkins todo.perch --diffs

v0

Not yet.

One object per file, one file per process, run locally. These are out of scope for v0:

  • WebSockets
  • env bindings and outbound fetch
  • npm imports (relative imports between the object’s own files work)
  • a server mode hosting many object files
  • sync between copies of a file
  • moving state to or from Cloudflare (export moves code and migrations, not data)

Related work: celld, and Rivet Actors.