Macrae

Updated 2026-10-09 · final state · all on Cloudflare, agents on Modal, voice by ElevenLabs

A research agent for Pavel Jungwirth's group at the IOCB (Institute of Organic Chemistry and Biochemistry of the Czech Academy of Sciences, Prague). You chat with Jarvis, by voice or by typing, and it answers like a capable assistant, citing the group's papers whenever they are relevant. When you start a task, it plans the run, does real computational chemistry in cloud sandboxes, writes a short manuscript, and shows you every paper it read, every calculation it ran and what it cost. It learns from its own traces: it notices a capability it lacks, creates it, tests it, installs it and uses it again, while its authority stays fixed.

1 · The pieces

Everything public sits behind one Cloudflare Worker (a small program on Cloudflare's network) at one address. The Worker serves the page and hands the browser a short-lived voice session. It forwards /api calls to the backend, adding a secret header the browser never sees. The backend is a Cloudflare Container, owned by a Durable Object: a named Cloudflare object that keeps exactly one instance and decides when it sleeps. The backend answers paper questions from its own index and runs tasks as agent-runner flows. Harbor starts each agent step in a sandbox on Modal and keeps the full trace; the sandbox also streams every step back while it works. Runs, traces, the capability registry and the paper index are mirrored to R2, Cloudflare's object storage. The typed chat, the planner and the lesson distiller call Claude through the Anthropic API from the container.

Abbreviations in the diagram: API = application programming interface · LLM = large language model · RAG = retrieval-augmented generation (search the papers first, then answer with what was found, citing it) · BM25 = "Best Match 25", a keyword-ranking formula · vCPU = virtual processor core · GiB = gibibyte · CPU / GPU = central / graphics processing unit · PySCF = Python-based Simulations of Chemistry Framework · ATIF = Agent Trajectory Interchange Format (Harbor's trace file).

2 · Status

Checked on the live site on 2026-10-09 after the last deploy. "Live" means on the public site and checked there; "tested" means merged and covered by tests (Harbor, Modal and Claude faked), not re-run live; "not built" means planned only.

3 · What happens when you…

4 · Where the traces are

A trace is everything one run did: the plan, every message, tool call and result, every file written, every check, and what it cost. Anyone can read it on the page and download it; the owner also has the raw copy in R2. The full guide is docs/TRACES.md in the repository.

How the timeline fills in live: a wrapper around Claude Code inside the sandbox forwards each line of its output to POST /api/live/{run}/{step}, at most about 1 s late, with a per-run token (never the shared secret). The server stores these lines in <run>/live/<step>.jsonl and de-duplicates them against the final trajectory.json. Traces also feed learning: lessons for the next run, and python -m evolve export turns passing trajectories into a fine-tuning dataset.

5 · Costs

Every chat answer, run and step shows what it cost in money, split into LLM (large language model) dollars and compute dollars, and how long it took. A run's meter grows live while it runs; the header keeps a total for your session, with a small "what this cost" breakdown; and before you start a task the page estimates its cost and time from past runs. The price and rate tables in server/costs.py cite their sources and dates.

Typical numbers:

• A chat answer: a fraction of a cent to a few cents, shown under the answer.
• The ion–water calculation: about 5–10 min of an agent on Modal and about $0.25–0.75, almost all of it LLM; with the lab notebook and manuscript it is at the top of that range.
• Guard rails: a global daily spend cap (LLM + Modal, $20 by default) with a clear message when it is reached, a cap on runs active at once, rate limits, and a budget per run set by the planner.
• Hosting: standard-1 container about $29/month if it never sleeps, about $4–5/month at about 4 h/day. That is on top of the $5 Workers Paid plan. R2 stays in the free tier. An open, visible browser tab checks health every 20 s and keeps the container awake.
• Building Macrae itself: see section 10 ($23.90 API-equivalent for the first six modules).
• With a Claude subscription login, LLM dollars are the API-equivalent cost of the same tokens, not a bill.

6 · Research tasks

Two tasks are on the site, each a flow of script steps on the backend and a Claude Code agent in a Modal sandbox:

Planned, not built: two tasks on BFF (BayesicForceFields, the group's code for Bayesian learning of partial charges; Košťál, Shanks, Jungwirth, Martinez-Seara, JCTC 2026). Agents scouted the group's papers and the BFF code (research/scout/) and the owner approved two ideas: "Is 0.8 the right charge-scaling factor? A Bayesian answer with BFF" (acetate, ECC 0.70–0.90, a Bayes factor) and "Ca²⁺–acetate binding with error bars" (umbrella-sampling free energies from the BFF charge posterior, compared with Raman data). The wave that was to build them ran out of Claude session time.

7 · Frankenstein: an agent that builds itself

The hackathon brief: "By dawn, show a creature that learned to do things it could not do at dusk." Macrae notices a capability it is missing, creates it, tests it, installs it, and uses it again in later runs. Its capabilities may evolve; its authority may not. (SHA-256 = Secure Hash Algorithm, 256-bit: a fingerprint that changes if a single byte of the tool changes.)

• Capabilities are versioned, tested tools with a manifest: name, purpose, inputs/outputs, tests, SHA-256 fingerprint, the run that created it, created/tested/installed/last-used times and a use count. The registry lives under evolve/capabilities/ in the backend's state.
• Three kinds. Tools (scripts, e.g. a radial distribution function or a block-averaged error bar from a molecular dynamics trajectory); environment capabilities (a Dockerfile fragment with pinned packages, created when the traces show slow installs or version breakage, tested by building it on Modal and running a smoke command, then used as the task's image, with setup time recorded before and after); and writing capabilities (style rules, templates).
• Notes to self. During a run the agent keeps NOTES_TO_SELF.md: what it tried, what was slow, what to do differently. evolve reads it with the rest of the trace and writes lessons with evidence links. The Evolution tab shows them, run over run per task (setup time, total time, cost, errors).
• The ledger: GET /api/capabilities lists the capabilities and every event (gap, create, test, install, use, rejected) between dusk and dawn. The Capabilities section of the Evolution tab shows it as a timeline, with the installed capabilities and the fixed "Authority" card.
• Dusk → dawn benchmark, the proof. A fixed suite (the ion–water calculation for Na⁺ and K⁺) runs twice: at dusk, with nothing learned injected or mounted, and at dawn, with every installed capability and lesson. Per task it records success, reward, wall time, setup time, LLM $, compute $, errors and the capabilities used; a registry snapshot taken at dusk keeps the report reproducible. GET /api/dawn-report holds the comparison, and the Dusk → Dawn section of the Evolution tab shows it as a table with the deltas. Only the operator starts a benchmark: POST /api/benchmark/{dusk|dawn} with the X-Macrae-Admin header (the Worker secret MACRAE_ADMIN_SECRET, which the voice agent never has); the same holds for a hand-started forge and the kill switch.
• Raw traces: each run has "Download trace" (a zip) and "Open report" (offline HTML).

8 · Code map

9 · Where it runs: all on Cloudflare

The page, the Worker and the backend live on one Cloudflare account and one address, deployed with cloudflare/deploy.sh (which runs wrangler deploy). The backend is a Cloudflare Container, built from the same Docker image, and the Durable Object MacraeBackend owns it. It sleeps after 2 hours without use, but never while a run is going. Its disk is temporary, so the paper index is baked into the image, and everything the backend writes is mirrored to R2. The container reaches R2 through the Worker at a private address (r2.macrae), so it needs no S3 (Simple Storage Service) keys. On a restart, task starts pause and running flows get up to 14 minutes to finish, but a deploy that changes the image makes Cloudflare replace the container without waiting, so deploys happen when no run is active. Edits to the page alone don't restart the backend. The heavy work (agents, calculations) runs in Modal sandboxes. AWS (Amazon Web Services) was the first plan and is no longer used.

Open to everyone, no login. Each visitor gets an anonymous session id. Task starts are rate-limited per IP (Internet Protocol) address in the Worker and per address, per session, for the voice agent and globally in the backend, with a cap on runs active on Modal at once (4); chat answers are limited to 20 a minute per address. A daily spend cap ($20 by default) stops new paid work when reached, and the operator has a secret-protected kill switch. Every route validates its input, task inputs come from allowlists and never reach a shell, and paper text in tool outputs is handled as data, not as instructions. No secret reaches the browser, and the sandbox gets only what its step needs.

10 · How it was built

With agent-runner itself. A written contract (CONTRACT.md) fixed every interface. Then six Claude Opus 5.5 agents (high effort) built their modules at the same time across three Claude accounts, each in its own container. All six passed their checks on the first attempt.

The later waves used the same method (Claude Opus 5.5 through agent-runner and Harbor, one git branch or folder per agent, then an integrator agent that merges, fixes the seams and tests end to end):

• Integration and Cloudflare: the first integrator; the backend moved into a Cloudflare Container with R2; the chat redesign.
• Research: agents scouted the group's papers and the BFF code, proposed ideas, a simulated chemist and a compute engineer critiqued them, and the owner approved two.
• v2: live traces, costs, the planner, evolution. v3: Frankenstein (capabilities, fixed authority, dusk → dawn, the research protocol and manuscript), the RAG on the group's papers.
• Wave 4: ten agents in parallel on their own branches (chat answers, browser end-to-end tests, concurrency, costs for users, trace downloads, voice, public safety, the proof pack, design polish, docs). Many of them, and the integrator, hit the Claude session limit.
• Final integration (2026-10-09, night, by hand with Claude Code). The v3 apply had dropped the tasks module (checks.py, research.py, calc-image) while keeping the flows that call it, so every live task would have failed its check, and it had reverted the typed chat (/api/chat); both were restored. Four finished w4 branches (docs, costs, trace download, public safety) were merged; the other w4 jobs left nothing. agent-runner's until: had let rate-limited attempts count as passed; fixed. Three safety gaps were closed: the operator routes were open to any visitor, the chat had no limits, and what Macrae learned was not synced to R2. The v3 page (capabilities, dusk → dawn, manuscript) was built then, and the dusk → dawn benchmark ran on the live site.

11 · What the owner provides

Glossary