tollbooth

tollbooth

面向 AI Agent 的有状态后端。 Agent 是无状态的：会话结束后，它们就会忘记；它们无法等待，也无法监视。tollbooth 是一个小巧、可自托管的服务，为 Agent 提供无状态性使其无法拥有的五种能力：

原语	Agent 能获得什么	为什么它自己做不到
memory	跨会话存储 / 回忆事实	会话结束时，它的上下文也随之消失
watch	“自从我上次查看后，这个页面有什么变化？”	它无法记住页面之前的样子
render	将 JS 渲染的页面转换为干净文本（使用真正的 Chromium）	普通 fetch 无法运行 JavaScript
execute	运行 python/node/bash，获取 stdout/stderr/退出代码	有些运行环境没有内置沙盒
board	共享的、仅追加的日志和摘要，供独立启动的 Agent 协作	它们的会话和父进程没有重叠

每个响应都附带机器可读的回执（tool、price_usd、latency_ms、timestamp）。本地使用时一切免费；回执格式保持稳定，因此基于它构建的工具也能用于托管版。

快速开始（Docker）

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

或者从源代码构建：

docker compose up --build

或者不使用 Docker（render 还需要额外一步）：

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

与它交互

# 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 .

从 Agent 使用（MCP）

tollbooth 在 /mcp 提供远程 MCP 端点（可流式传输的 HTTP）——无需启动本地进程，因此也适用于能发起 HTTPS 请求、但无法安装任何内容的运行环境。

Claude Code：

claude mcp add --transport http tollbooth http://localhost:4402/mcp

提供的工具：memory_store、memory_recall、watch_add、watch_check、watch_list、render_extract、execute_run、board_open、board_list、board_post、board_read、board_digest。

教会你的 Agent 如何使用它

如果 Agent 不知道何时该使用某个工具，它就不会使用。本仓库提供了五个技能，位于 .claude/skills/：

技能	说明
tollbooth	何时使用各个原语，以及何时不必使用
checkpoint	按需将本次会话中有长期价值的结论保存到 board
janitor	将 board 精简为摘要（使用轻量模型运行）
warmstart	使用 board 为新会话预热，而不是重新阅读对话记录（为避开保留的 /resume 内置命令而命名）
toolbox	机器全局的问题 → 有效工具日志（在 memory 中使用 ns=toolbox）：构建前先回忆，只存储你亲眼确认有效的内容

将它们复制到 ~/.claude/skills/，即可在每个项目中使用（也可以复制到某个项目的 .claude/skills/）；或者将其内容用作非 Claude 运行环境（GPT、DeepSeek、GLM、Grok）的系统提示词章节（API 使用纯 HTTP，因此相同的指令可在任何地方使用）。

cp -R .claude/skills/* ~/.claude/skills/

如需零 token 的上下文捕获，scripts/tollbooth-hook.mjs 会自动将每个会话结束时的上下文发送到对应项目的 board — 有关一次性 hook 设置，以及将这些捕获内容转为预热内容的轻量模型摘要方案，请参阅 docs/warm-start.md。

配置

环境变量	默认值	含义
PORT	4402	HTTP 端口（402 = Payment Required——这个玩笑就是路线图）
TOLLBOOTH_DATA_DIR	./data	SQLite 状态数据的存放位置
TOLLBOOTH_TIER	local	cloud 会在目录 / 回执中启用非零价格

关于 execute 的安全说明

容器就是沙盒边界：提交的代码会以容器权限运行。如果不受信任的 Agent 能访问 tollbooth，请在随附的 Docker 镜像（或等效的一次性容器）中运行 tollbooth，切勿直接在你在意的机器上运行。

路线图

• 后台轮询监视 + Webhook（真正的“通知我”，而不只是按需比较差异）
• 托管版：在相同 API 后接入 Stripe 额度和 x402 按次付费，供无法自托管的沙盒中的 Agent 使用
• distill（针对目标压缩日志 / HTML / 仓库），作为免费的本地工具

许可证

MIT