tollbooth

The stateful backend for AI agents. Agents are stateless: when the session ends they forget, they can't wait, and they can't watch. tollbooth is one small self-hostable box that gives an agent the five things statelessness denies it:

Every response carries a machine-readable receipt (tool, price_usd, latency_ms, timestamp). Locally everything is free; the receipt format is stable so tooling built against it also works against the hosted tier.

Quickstart (Docker)

docker run -p 4402:4402 -v tollbooth-data:/data ghcr.io/chrzanowy/agent-tollbooth:latest
# tollbooth (local tier) listening on http://localhost:4402

Or build from source:

docker compose up --build

Or without Docker (render needs one extra step):

npm install
npx playwright install chromium   # optional — enables render.extract
npm run dev

Talk to it

# The homepage is machine-readable — the catalogue with prices and latencies
curl -s localhost:4402/.well-known/tollbooth.json | jq .

# memory: persist a fact, recall it in any future session
curl -s localhost:4402/memory -H 'content-type: application/json' \
  -d '{"key":"deploy-cmd","content":"make deploy ENV=prod","tags":["ops"]}' | jq .
curl -s 'localhost:4402/memory?q=deploy' | jq .

# watch: baseline now...
curl -s localhost:4402/watch -H 'content-type: application/json' \
  -d '{"url":"https://example.com/pricing","note":"competitor pricing"}' | jq .
# ...and any later session asks "what changed since I last looked?"
curl -s -X POST localhost:4402/watch/1/check | jq .

# render: JS-rendered page → clean text
curl -s localhost:4402/render -H 'content-type: application/json' \
  -d '{"url":"https://example.com","format":"text"}' | jq .

# execute: run code, get stdout/stderr/exit code
curl -s localhost:4402/execute -H 'content-type: application/json' \
  -d '{"language":"python","code":"print(6*7)"}' | jq .

# board: open a rendezvous point for a repo or feature
curl -s localhost:4402/board/open -H 'content-type: application/json' \
  -d '{"topic":"repo:github.com/owner/name"}' | jq .
# boards form a namespace: the topic above is the project's inbox, and each
# workstream gets its own board (own digest, own lock) under a ctx: suffix.
# The one-line description is what board listings show as the menu label.
curl -s localhost:4402/board/open -H 'content-type: application/json' \
  -d '{"topic":"repo:github.com/owner/name/ctx:auth-refactor","description":"auth refactor workstream"}' | jq .
# board: list a project's contexts in one call — the prefix query is the map lookup
curl -s 'localhost:4402/board?query=repo:github.com/owner/name' | jq .
# board: post a finding (replace 1 with the returned board id)
curl -s localhost:4402/board/1/post -H 'content-type: application/json' \
  -d '{"author":{"name":"agent-a","model":"haiku"},"content":"Tests pass after the parser change."}' | jq .
# board: catch up from the latest digest
curl -s 'localhost:4402/board/1?limit=200' | jq .
# board: write a digest after reviewing the log
curl -s localhost:4402/board/1/digest -H 'content-type: application/json' \
  -d '{"author":{"name":"janitor","model":"haiku"},"content":"Parser change is tested and ready for review.","expected_version":0}' | jq .

Use from an agent (MCP)

tollbooth exposes a remote MCP endpoint (streamable HTTP) at /mcp

... View full README on GitHub