flue-sandbox-agent-shell

A Flue agent that runs in a Tigris-backed sandbox. Each run forks a canonical bucket, gives the agent a private /workspace mounted on the fork, and tears the fork down on exit.

The bucket is provisioned by @tigrisdata/agent-kit. The shell the agent sees is @tigrisdata/agent-shell, wired into Flue through a small adapter in connectors/agent-shell.ts.

The agent

agents/content-review.ts is a trust & safety reviewer. Point it at a bucket of mixed content and it will:

1. Fork the bucket so the working copy is disposable and so any mistakes don't delete data for good.
2. Mount the fork at /workspace through TigrisShell.
3. Walk the tree, classify each file, and return a structured report ({ report, flagged_paths }).
4. Flush the shell so any moves persist back to the fork.
5. Tear the fork down.

The reviewer prompt lives inline in content-review.ts. It is explicit about what to flag (CSAM, hate speech, credible threats, doxxing, working malware, live secrets) and what to leave alone (mature fiction, security research, ugly code).

Why fork instead of mounting the source bucket

createForks from agent-kit produces a per-run copy-on-write fork of the canonical bucket with its own scoped credentials. The agent can move, rewrite, or destroy whatever it wants inside /workspace without touching the source. teardownForks runs in a finally block, so the fork goes away even if the agent throws.

Prerequisites

• Node 22+
• A Tigris bucket and access key with permission to fork it
• An LLM provider key for the model configured in app.ts

Copy .env.example to .env and fill in:

ANTHROPIC_API_KEY=        # optional, only if you switch the model
TIGRIS_STORAGE_ACCESS_KEY_ID=
TIGRIS_STORAGE_SECRET_ACCESS_KEY=
TIGRIS_STORAGE_BUCKET=    # the canonical bucket to fork from

Commands

npm run dev        # watch-mode server on :3583
npm run build      # emit ./dist
npm start          # run the built server (defaults to :3000)
npm run typecheck  # tsc --noEmit

Invoking the agent

Over HTTP, while npm run dev is running:

curl http://localhost:3583/agents/content-review/run-1 \
  -H "Content-Type: application/json" \
  -d '{"focus": "uploads/2026-05"}'

The run-1 segment is the durable instance ID. Reuse it to continue the same session; change it to start fresh.

One-shot, without booting the server:

npx flue run content-review \
  --target node \
  --id run-1 \
  --env .env \
  --payload '{"focus": "uploads/2026-05"}'

Layout

agents/
  content-review.ts     # the agent handler + reviewer prompt
connectors/
  agent-shell.ts        # adapts TigrisShell to Flue's SandboxFactory
app.ts                  # provider registration + Hono app
manifest/app.yaml       # deploy manifest
Dockerfile              # production image

Flue reads from the project root. If you ever add a .flue/ directory, Flue switches to that layout and stops reading these files — keep one or the other, not both.

Notes on the sandbox adapter

agentShell(shell) wraps an already-constructed TigrisShell into a SandboxFactory. The agent owns the shell's lifecycle: construct it, call flush() before returning, tear it down in finally. The connector deliberately never flushes on the caller's behalf, so a thrown error leaves the cache untouched and recoverable.