Flarebot #

A persistent personal agent in your own Cloudflare account. The v0.1 client uses OctaneJS and the Octane port of Kumo. The runtime uses Cloudflare Agents, Think, Workers AI, durable storage, browser tools and scheduled execution.

Multi-step web research uses Cloudflare Code Mode to compose searches, URL reads and browser renders inside an isolated Worker. Each batch permits 12 calls, runs up to 3 concurrently, and has a 45-second deadline. Nested calls retain tool activity, cancellation and browser lease cleanup. Single-page reads remain available directly. The generated code has access only to these research tools; source content and exact URLs are returned to the model for interpretation and citation. Code Mode is pinned as an experimental dependency.

Development #

Use Node 24 (see .node-version) and the pnpm version in package.json.

pnpm install --frozen-lockfile
pnpm dev

Vite serves the frontend and Octane server routes with hot reload. To run the production frontend and Worker together in the local Cloudflare runtime:

cp .dev.vars.example .dev.vars
pnpm dev:worker

Wrangler serves the application at http://localhost:8787. Rebuild after source changes. Local Worker state is stored in .wrangler/. Open /auth/login once to create the development owner session; this shortcut is restricted to an explicit development environment on a loopback runtime origin.

Kumo is installed from a pinned commit of the separate octane-kumo repository. A sibling checkout is not required. Work on that port belongs in its repository. The published sidebar currently requires browser APIs, so the shell uses TanStack Router's ClientOnly boundary with server-rendered navigation and page content until hydration.

Model selection #

The chat composer uses Octane Kumo model and effort selectors. Choices are saved with the next message or retry, apply only to that conversation, and cannot change an in-flight response. Changing models resets effort to the provider default. Only verified model-specific effort levels are offered; there are no token-budget inputs or synthetic effort-to-budget mappings.

Settings retains provider credentials and the installation's default model/effort. Chats using Installation default refresh it before sending. Scheduled tasks snapshot that default when submitted, independently of the chat's override. Provider default omits effort options; explicit effort uses a bounded 16,384-token total output allowance (including reasoning), rather than the usual 4,096. Higher effort can increase latency and cost.

Validation #

Use the daily gate for sub-minute local feedback:

pnpm test

This runs frontend and Worker typechecking, pure configuration/provider/storage and Effect checks, plus small native Workers tests for attachments, deployment networking and customer runtime boundaries. It needs no packaged assets, browser or container. pnpm test:quick runs only the pure tests, without typechecking.

Run the exhaustive suite before shipping:

pnpm exec playwright install chromium # Once, after installing dependencies
pnpm test:full

The full command typechecks, builds the customer release and development publisher fixture, then discovers all test files, including browser, container and real-time cron/recovery checks. Live provider tests retain their existing opt-in environment flags. Catalog tests finish before publisher packaging because they rewrite shared build outputs. The ownership restart suite runs alone because it currently hits intermittent connection resets under load.

Both commands use up to four test processes, limited by available CPUs and one process per 2 GiB of RAM. Each Node test process limits V8 old-space to 512 MiB; native Workers, browsers and other allocations use additional memory. Set FLAREBOT_TEST_CONCURRENCY=1 for serial execution, or raise it on a machine with spare CPU and memory. Do not run builds or another full suite in the same checkout while tests consume packaged assets.

Container tests require a compatible Docker API socket. With rootless Podman on Linux, expose its socket before running the full suite (runtime compatibility is still required):

systemctl --user start podman.socket
export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/podman/podman.sock"
pnpm test:full

pnpm test:execution also runs its lifecycle, unattended recovery and real cron fixtures with bounded parallelism. Their native clocks and restart assertions are preserved, but the long alarm waits can overlap. Unattended cases wait for outgoing Worker completion notifications instead of adding fixed safety sleeps; those notifications do not wake the Worker with a read. The cancellation fixture holds model output until the test explicitly releases it. Existing FLAREBOT_EXECUTION_CASE filters apply to all three fixtures.

Individual checks remain available after building the necessary assets:

pnpm typecheck
pnpm test:config
pnpm build:release
pnpm test:worker
pnpm test:deployment
pnpm test:settings
pnpm test:app-shell

The Worker smoke test checks rendered navigation, client assets and HTTP 404s using the local Cloudflare runtime. CI runs these checks for every pull request, including PRs based on another issue branch. Deployment is a separate, explicit pnpm deploy command.

The Worker requires typed installation settings and an independent session secret. See configuration and secrets for production setup, local overrides and the customer/control-plane boundary. .dev.vars and its environment variants are ignored; only the placeholder example is committed. Vite alone is a frontend preview and does not validate Worker bindings. Never put secrets in client source, Vite environment variables or wrangler.jsonc.

The customer deployment contract documents required resources, stable identities, account boundaries and the versioned dist/release artifact.

The Effect control plane describes backend execution, native persistence boundaries, and the Distilled Cloudflare SDK's coverage and gaps.

The Effect customer runtime describes application composition, native resource ownership, and migration validation. The original migration plan records the scope and gates.

The v0.1 golden-path gate connects native installation, owner login, memory, research, shell execution and unattended scheduled work.

See the application shell for navigation, authenticated connection behavior, and the boundary between shell metadata and native conversations.

The TanStack Query migration plan describes the proposed browser server-state cache, starting with Settings and shared conversation metadata, with implementation phases and behavioral validation.