tollbooth

io.github.chrzanowy由 GitHub 账号 chrzanowy 发布v0.1.2更新于 Oct 24, 2026

Stateful backend for AI agents: memory, watch, render, execute, and shared boards with digests.

已验证STDIO仅桌面浏览器自动化知识与记忆开发者工具

概览

AI 生成的概览

可自托管的 AI 智能体有状态后端，通过远程 MCP 端点提供跨会话记忆、网页变更监控、JS 渲染、代码执行和共享看板。

可以做什么
用带标签的记忆条目和搜索查询跨会话存储与召回事实，让上下文在会话结束后仍保留。为网页建立基线，之后检查自上次查看以来的变化，并列出已跟踪的监控项。使用真实 Chromium 将依赖 JavaScript 的页面渲染为纯文本。运行 Python、Node 或 Bash 代码并返回标准输出、标准错误和退出码。打开、列出、发布和读取共享的只追加看板，并写入摘要以压缩看板日志供其他智能体使用。
适用场景
适用于智能体需要在会话之间记住结论、监控页面变化、读取 JavaScript 渲染内容、运行小段脚本，或通过共享看板与独立启动的智能体协作的场景。最适合由你掌控容器的自托管环境。
运行要求
以本地 Docker 容器运行（镜像发布在 ghcr.io），或用 Node.js 与 npm 从源码构建；Playwright Chromium 安装为可选项，仅 render 需要。通过 streamable HTTP 暴露远程 MCP 端点，通常使用 4402 端口。可选环境变量 PORT、TOLLBOOTH_DATA_DIR 和 TOLLBOOTH_TIER 分别配置端口、SQLite 数据位置和计价层级。未声明身份验证。
安装前请注意
execute 工具以容器权限运行提交的代码，容器是唯一的沙箱边界；若有不受信任的智能体能访问它，应使用官方 Docker 镜像或一次性容器运行，切勿直接运行在你在意的机器上。未声明身份验证，任何能访问该端点的人都能使用记忆、看板和代码执行。记忆与看板内容会持久保存在数据目录下的 SQLite 中。cloud 层级会在回执中启用非零价格。

安装

在 SourceWeft 中

  1. 打开 控制台中的 tollbooth，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

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:

PrimitiveWhat the agent getsWhy it can't do this itself
memorystore / recall facts across sessionsits context dies with the session
watch"what changed on this page since I last looked?"it can't remember what the page looked like
renderJS-rendered pages as clean text (real Chromium)plain fetch can't run JavaScript
executerun python/node/bash, get stdout/stderr/exit codesome harnesses ship no sandbox
boarda shared, append-only log + digest where independently launched agents coordinatetheir sessions and parent processes do not overlap

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)

sh
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:

sh
docker compose up --build

Or without Docker (render needs one extra step):

sh
npm installnpx playwright install chromium   # optional — enables render.extractnpm run dev

Talk to it

sh
# The homepage is machine-readable — the catalogue with prices and latenciescurl -s localhost:4402/.well-known/tollbooth.json | jq .
# memory: persist a fact, recall it in any future sessioncurl -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 textcurl -s localhost:4402/render -H 'content-type: application/json' \  -d '{"url":"https://example.com","format":"text"}' | jq .
# execute: run code, get stdout/stderr/exit codecurl -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 featurecurl -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 lookupcurl -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 digestcurl -s 'localhost:4402/board/1?limit=200' | jq .# board: write a digest after reviewing the logcurl -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 — no local process to spawn, so it also works from harnesses that can make HTTPS calls but can't install anything.

Claude Code:

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

Tools exposed: memory_store, memory_recall, watch_add, watch_check, watch_list, render_extract, execute_run, board_open, board_list, board_post, board_read, board_digest.

Teach your agent to use it

A tool an agent doesn't know when to reach for goes unused. This repo ships five skills under .claude/skills/:

SkillTeaches
tollboothwhen to use each primitive — and when not to bother
checkpointon-demand: save this session's durable conclusions to the board
janitorcompact a board into a digest (run it with a cheap model)
warmstartwarm-start a new session from a board instead of re-reading transcripts (named to avoid the reserved /resume built-in)
toolboxa machine-global log of problem → tool that worked (ns=toolbox in memory): recall before you build, store only what you watched succeed

Copy them into ~/.claude/skills/ to have them in every project (or into one project's .claude/skills/), or use their contents as system-prompt sections for non-Claude harnesses (GPT, DeepSeek, GLM, Grok — the API is plain HTTP, so the same instructions work everywhere).

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

For zero-token context capture, scripts/tollbooth-hook.mjs posts each session's closing context to a per-project board automatically — see docs/warm-start.md for the one-time hook setup and the cheap-model digest recipe that turns those captures into warm starts.

Configuration

Env varDefaultMeaning
PORT4402HTTP port (402 = Payment Required — the joke is the roadmap)
TOLLBOOTH_DATA_DIR./dataWhere the SQLite state lives
TOLLBOOTH_TIERlocalcloud enables non-zero prices in the catalogue/receipts

Security note on execute

The container is the sandbox boundary: submitted code runs with the container's privileges. Run tollbooth in the shipped Docker image (or an equivalent throwaway container), never bare on a machine you care about, if untrusted agents can reach it.

Roadmap

  • Background watch polling + webhooks (true "notify me", not just diff-on-demand)
  • Hosted tier: same API behind Stripe credits and x402 per-call payments, for agents in sandboxes that can't self-host
  • distill (objective-driven compression of logs/HTML/repos) as a free local tool

License

MIT

来源：README.md，提交 08f8a47

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.1.2最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分