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 分