sark

🤔 Why?

Running a coding agent from chat is easy to demo and hard to make safe. The moment more than one person can mention the bot, you need answers to:

• 🧨 where does the agent's code actually run, and what else can it touch?

• 🧵 how do two threads avoid trampling each other's files?

• 🔓 what stops a public channel from spinning up unbounded sandboxes?

• 🤐 what happens when the agent finishes but never says anything?

• 🎭 when five people talk at once, who does the agent think it's answering?

sark is one answer. Every Slack thread gets its own forked sandbox on ascii.dev Box. The agent inside talks back through an MCP server hosted by this Worker, using a token that can only ever address the one thread it was minted for. The allowlist fails closed, nothing holds ambient authority, and no two threads share a filesystem.

Related MCP server: claude-slack-bridge

✨ Highlights

📦 Requirements

• An ascii.dev Box account — this Worker is a control plane for Box sandboxes and does nothing without one. You need a box_... API key.

• Cloudflare Workers with Durable Objects. The per-thread state machine is a DO with a SQLite backend, which is not available on the free plan.

• Node 22+ and the box CLI (for npm run dev-vars).

• A Slack app is optional — the /api surface exercises the whole pipeline without it.

Throughout the docs, https://<your-worker>.workers.dev stands in for your own deployed origin. Your real settings go in .deploy.env (gitignored), never in wrangler.jsonc — see Setup.

🚀 Quickstart

npm install
npm run dev-vars          # 🔑 writes .dev.vars (BOX_API_KEY comes from your `box` CLI login)
npm run dev               # ⚡ local worker on :8787

# one command: trigger, follow, print the agent's replies
npm run drive -- --thread demo "create hello.txt with the word banana and tell me what you did"
npm run drive -- --thread demo "what was in that file?"   # 🧵 same thread => same sandbox
npm run drive -- --thread demo --stop                     # 💤 archive the sandbox

That's the whole core loop, with no Slack app involved.

🧪 Testing without Slack

The /api surface drives the exact same Durable Object path — only the trigger and the output sink differ. With MemoryTransport, everything the agent "says" is recorded and readable back.

For the agent to actually reach /mcp, PUBLIC_URL must be publicly reachable, so full end-to-end runs go against the deployed Worker:

npm run drive -- --url https://<your-worker>.workers.dev --thread demo "hello"

Against a local worker the box cannot call back, so the run exercises the watchdog fallback path instead (the reply is recovered from the box event log).

🔌 API

All routes require Authorization: Bearer $API_TOKEN, and fail closed (503) if API_TOKEN is unset.

{id} is any opaque string. Slack threads use {team}:{channel}:{thread_ts}, so a live Slack conversation can be inspected through the same API.

curl -sX POST localhost:8787/api/threads/t1/prompt \
  -H "Authorization: Bearer $API_TOKEN" -H 'content-type: application/json' \
  -d '{"text":"run the tests","metadata":{"ticket":"ENG-42"}}'

Anything in metadata is passed through into the prompt's context block. Prompt text is capped at 16k characters: /api rejects anything longer with a 413, while Slack input is truncated rather than refused.

🧰 MCP tools

The agent inside the box gets exactly five tools, none of which take a channel or thread parameter — the destination is fixed by the token:

slack_post_message · slack_update_message · slack_add_reaction · slack_upload_file · slack_get_thread

🛠️ Setup

1. Template box (optional but recommended)

Without TEMPLATE_BOX_ID each thread gets a fresh box. With one, threads fork a snapshot that already has your stack, repos, and MCP settings.

box new                      # 📦 install your stack, clone repos
box stop <id>                # 📸 the snapshot IS the template
# put TEMPLATE_BOX_ID=<id> in .deploy.env

Keep the template stopped; resume → update → stop to publish a new version.

2. Deploy

npx wrangler secret put BOX_API_KEY        # box_... from the Box dashboard
npx wrangler secret put MCP_TOKEN_SECRET   # any long random string
npx wrangler secret put API_TOKEN          # guards /api

Then put your settings in .deploy.env (gitignored) and deploy:

WORKER_NAME=sark
PUBLIC_URL=https://<your-worker>.workers.dev   # the box reads this to find /mcp
ALLOWED_CHANNELS=C0123456789
ALLOWED_TEAMS=T0123456789

npm run deploy

wrangler.jsonc is the public template and stays that way: placeholder origin, empty allowlists, no account_id. npm run deploy injects your values as wrangler overrides, and npm run check-config fails the build if real ones ever reach the tracked file. Nothing personal can be committed by accident.

3. Slack (optional)

Create the app from slack-manifest.json, install it, then:

npx wrangler secret put SLACK_BOT_TOKEN      # xoxb-...
npx wrangler secret put SLACK_SIGNING_SECRET

Set ALLOWED_CHANNELS / ALLOWED_USERS in .deploy.env (and optionally ALLOWED_TEAMS to pin the workspace). The allowlist fails closed — with both empty, every mention is refused. This is what stops a public channel from spinning up unbounded sandboxes. It gates /slack/events only; /api is behind API_TOKEN and bypasses it by design.

The manifest enables interactivity and points it at /slack/interactive, which handles only the 🧠 effort dropdown. That handler verifies the signature and runs the same isAllowed gate as a mention before acting. Without the gate, anyone who could see the message could drive the sandbox.

Say stop in a thread to interrupt the running agent.

🎛️ Emoji controls

The status message carries buttons for whatever makes sense right now. While a run is going that is Stop and Watch; once it is over, stopping means nothing and the buttons become Re-run, Effort, Fork, and Archive. Fork and Archive open a native confirm dialog first, because one spends money and the other kills a live sandbox.

The same six actions also work as emoji reactions on any message in the thread, which buttons cannot do since they only live on the status message:

The reactions are not pre-seeded. Six emoji on every status message outlived their meaning, and pre-seeding the costly ones is an invitation to click them.

Reactions are ordinary Events API events, so they arrive at /slack/events behind the same signature check and the same fail-closed allowlist as a mention. A reaction from someone the allowlist doesn't cover is dropped silently. Replying would turn any emoji in a public channel into a way to make the bot talk.

A reaction_added payload carries item.{channel,ts} and no thread_ts, so the thread is recovered with one conversations.replies call. That method accepts the ts of any message in a thread and answers parent-first, so messages[0].ts is the thread. A reaction on a thread with no session does nothing. Reacting can only act on a sandbox that already exists, never create one.

🍴 Forking a conversation

🍴 opens a new top-level thread in the same channel and gives it a fork of this thread's box, so it starts from the current filesystem without disturbing the original. Use it to try two approaches from one setup, or to peel a tangent off a long thread. The new thread is opened first because its ts is the thread id baked into the forked box's env, and box env is fixed at fork time.

🧠 How it holds together

flowchart TB
    subgraph slack["Slack"]
        mention["@mention in a thread"]
    end
    subgraph worker["sark Worker (Hono)"]
        ev["/slack/events<br/>verify · dedupe · allowlist"]
        api["/api/*<br/>API_TOKEN"]
        mcp["/mcp<br/>thread-scoped HMAC"]
    end
    do["ThreadSession (Durable Object)<br/>fork → bootstrap → prompt → watchdog → idle-stop"]
    box[("Box sandbox<br/>claude-code")]

    mention --> ev
    ev --> do
    api --> do
    do -->|fork · POST /prompt| box
    box -->|MCP over HTTP| mcp
    mcp --> do
    do -->|chat.postMessage| slack

🔐 Thread-scoped MCP tokens. The box calls back with a stateless HMAC token that names one thread and one box generation, and carries an issue time enforced on every use. So it only ever addresses the thread it was minted for, only while that exact box is still the thread's box, and only for 12 hours; ensureMcp re-mints and re-registers once a token is half-way to expiry, so long threads rotate rather than expire mid-run. The token is not a box env var — env is fixed at fork time, which would pin a box to one credential for life. It is written to a file the bootstrap script reads and deletes as it registers the server. The box env carries only SLACK_MCP_URL, SLACK_THREAD_ID, and (for Slack threads) SLACK_CHANNEL, SLACK_THREAD_TS, SLACK_TEAM. The MCP tools have no channel or thread parameter at all, and /mcp caps a request at 32 batched calls and 1MB, so a compromised box cannot post anywhere else in the workspace or use the endpoint as an amplifier.

🐕 The watchdog. The agent is supposed to reply via MCP, but it can fail to. A Durable Object alarm polls the prompt status; if the run finishes or fails with nothing said, the reply is recovered from the box event log and posted anyway — the thread never goes silent. Silence also clears the MCP registration flag, so the next turn re-registers and self-heals.

💤 Lifecycle. Idle threads archive their box after IDLE_STOP_SECONDS (snapshotting it). A later message resumes it onto the same filesystem and re-registers MCP with a fresh token.

🧵 One run per thread. A thread runs a single agent prompt at a time. Messages that arrive while a run is in flight are queued in the Durable Object; when the run finishes they are drained into one batched turn (not replayed one by one). Each message is rendered as its own <message> block carrying its own sender, message id, permalink, and /api metadata, so the agent attributes every request to the person who actually made it — not to whoever spoke first. Message bodies, display names, and metadata are untrusted text, so the delimiters the prompt is built from are neutralized inside them: a user cannot close their own block and open one under someone else's name. The queue holds at most 20 messages; past that, further messages are refused with a notice rather than piling up work nobody is still waiting for. Different threads never contend; each has its own box.

📁 Layout

🙅 Not in scope

sark is deliberately small. It does not try to be:

• 🏢 a multi-tenant SaaS — one Worker, one Box account, one workspace's allowlist

• 💬 a general Slack framework — five tools, two event types, one dropdown, no slash commands

• 🧮 a job queue — one run per thread, a bounded backlog, and no cross-thread scheduling

• 🔗 a bridge to other chat platforms — though Transport is the seam where one would go

🤝 Contributing

PRs welcome. Before sending:

npm run typecheck
npm test           # 🧪 96 tests (node + a workerd project for the Durable Object)
npm run smoke      # 🔍 verify Box API access and template

See CONTRIBUTING.md for conventions, and SECURITY.md to report a vulnerability — please don't open a public issue for anything exploitable.

📜 License

MIT — see LICENSE.