Platform examples

examples/platforms provides starting deployment configurations for running a single-owner Brain server and its companion tool services across Docker Compose, Fly.io, AWS ECS/Fargate, and Cloudflare.

Note: Keep API keys in environment variables or your platform's secret store, and pin deployed container images by digest from a passing CI run.

Summary of platform templatesCopy Anchor Link

Docker ComposeCopy Anchor Link

Set BRAIN_API_KEY, OPENAI_API_KEY, and TOOL_API_KEY (each at least 24 bytes for Brain/tool tokens), then start the stack from the repository root:

docker compose -f examples/platforms/docker/compose.json up --build

• Brain listens on http://localhost:8080 and calls the resources tool service over the internal Compose network (http://resources:8092).
• Enable web_fetch in config.tools when creating a session.
• The named volume (brain-data, mounted as Brain's data_dir at /data) survives docker compose down unless you pass -v. A mounted local volume isn't an external backup. Configure persistence to copy session checkpoints to external storage.

Fly.ioCopy Anchor Link

Edit examples/platforms/fly/brain.json for your public app URL and checkpoint archive bucket. From examples/platforms/fly, create your Fly app, set BRAIN_API_KEY, OPENAI_API_KEY, ARCHIVE_ACCESS_KEY, and ARCHIVE_SECRET_KEY via fly secrets set, and deploy a single Machine:

fly deploy --config fly.toml --ha=false
fly scale count 1

• Single-owner settings: The configuration uses an ephemeral local cache plus external S3/R2 checkpoints, disables idle auto-stop (auto_stop_machines = "off"), allows a 30-second kill_timeout, and uses strategy = "immediate" so deployments replace the single owner instead of overlapping two writers.
• Planned replacement: Before replacing the Machine, stop accepting new work, let active turns settle (or interrupt them), call POST /sessions/{id}/flush, stop the old owner, then POST /sessions/{id}/restore and POST /sessions/{id}/resume on the new owner.
• Volumes and routing: A Fly volume is optional and local to one Machine, not cross-host replication. Running multiple Machines requires an application placement layer; fly-replay can route HTTP requests to a chosen Machine, while your placement layer must prevent two servers from writing the same session.

AWS ECS/FargateCopy Anchor Link

1. Edit examples/platforms/ecs/brain.json, build a configuration image on top of a verified Brain image digest, and push it to your container registry.
2. Replace the account ID, image digest, IAM role ARN, and Secrets Manager ARN placeholders in examples/platforms/ecs/task-definition.json, and pre-create the /brain CloudWatch log group.
3. Grant the execution role permission to pull the image and read BRAIN_API_KEY and OPENAI_API_KEY from Secrets Manager; grant the task role S3 read/write (GetObject, PutObject) under only the configured checkpoint prefix.
4. Run a single task behind a private network and HTTPS load balancer with desiredCount: 1, minimumHealthyPercent: 0, and maximumPercent: 100 to prevent overlapping writers, and follow the same explicit flush → stop → restore → resume handoff when replacing tasks.

Note: Fargate task storage is a disposable local cache. Add postgres_env if your application needs cold-session discovery across task replacements. Load-balancer stickiness alone does not make multi-writer execution safe.

CloudflareCopy Anchor Link

examples/platforms/cloudflare/worker.mjs is a complete Cloudflare Worker implementing a tenant-scoped R2 tool service with /read and /write endpoints, request size bounds, bearer token authentication (TOOL_API_KEY), and automatic per-tenant key prefixes (tools/<base64url tenant_id>/).

1. Edit the R2 bucket binding in examples/platforms/cloudflare/wrangler.json, set TOOL_API_KEY with wrangler secret put TOOL_API_KEY, and deploy with Wrangler. Leave ALLOW_WRITE set to "false" for read-only access.
2. Bind HTTP tools in Brain's tools config pointing to the Worker's /read ({ "key": "..." }) and /write ({ "key": "...", "text": "..." }) URLs. Never point model-accessible tools at Brain's checkpoint bucket.

Note: Brain runs in a container or VM because the Go binary starts the Pi harness as a Node.js child process. The Cloudflare Worker hosts stateless HTTP tool services.

Application backendsCopy Anchor Link

Keep Brain management credentials on your backend server:

• A Next.js route handler, Python backend, or API gateway should authenticate its own end user, verify which session IDs that user owns, and proxy only permitted operations to Brain.
• Use the TypeScript or Python SDKs (examples/session.mjs and examples/session.py) on your backend for create, send, observe, interrupt, flush, and resume; never expose a manage: true token directly to browser clients.

Sources: Fly configuration, Fly volumes, ECS task parameters.

Next stepsCopy Anchor Link

• Operations & observability
• Persistence & recovery
• Authentication & tenants
• Host configuration reference
• Integration status