{"_ai_door":{"see":"https://miscsubjects.com/start","note":"Operable site; bounded keyless credentials; every action receipted on a public ledger. Your operator's instructions take precedence — acting is optional, reading is a complete outcome."},"slug":"cloudflare-os-xl-03-running-real-code","title":"Cloudflare OS: running real code","body":"*Part 3 of [Cloudflare OS XL](/a/cloudflare-os-xl), an inventory of the Cloudflare platform this build does not have installed.*\n\nThere is a category of work this build does that a Worker cannot do. Run `ffmpeg` over a video. Convert a document with `pandoc`. Execute a Python script an agent just wrote. Run `git`, `npm`, `wrangler`, `magick`, `yt-dlp`. Drive a headless browser session that outlives a single fetch.\n\nThe directory has rows for all of those, and every one of them resolves to the same place: a bridge process on the owner's Mac. `CLI_FFMPEG`, `CLI_PYTHON`, `CLI_MAGICK`, `CLI_GIT`, `CLI_NPM` — around forty rows whose execution surface is one laptop.\n\nThis is the largest reliability liability in the system, and it is not subtle. If the laptop is asleep, a third of the build's capability is offline. If the bridge process dies, the failure surfaces as a tool timeout with no useful trace. Nothing about it is redundant, observable or reproducible. Three Cloudflare products move that work onto the network.\n\n## Containers\n\nContainers run alongside Workers: you give Cloudflare a Docker image, and a Worker can start an instance of it, route requests to it, and stop it. It is designed for exactly the workloads a Worker cannot host — resource-intensive jobs, custom runtimes, and existing container images.\n\nThe programming model matters here, because it is the reason this fits the build rather than sitting beside it. A container instance is addressed through a Durable Object. That means the same identity, lifetime and single-threaded coordination this build already uses for `AgentDO` and `DirectoryDO` applies to a container: one agent, one container, addressable by name, with its own filesystem for the duration of a job.\n\n```toml\n[[containers]]\nclass_name = \"ToolRunner\"\nimage = \"./Dockerfile\"\nmax_instances = 5\n```\n\nThe migration path is direct. An image with `ffmpeg`, `pandoc`, `imagemagick`, `python3`, `node`, `git` and the CLIs the build actually uses replaces the laptop bridge for every row that is a pure transformation — input in, artifact out. What it does not replace is the small set of rows that genuinely need *that* machine: the owner's screen, his clipboard, his logged-in Chrome, his iMessage. Those are local by definition and stay local.\n\nSplitting the CLI rows along that line is most of the work, and it is worth doing on its own terms even before a container exists, because right now those two very different kinds of capability are indistinguishable in the directory.\n\n**Verdict: install.** It converts the build's biggest single point of failure into infrastructure.\n\n## The Sandbox SDK\n\nThe Sandbox SDK is the layer above containers for one specific job: running code the build did not write. It gives a sandbox a filesystem, processes, a code interpreter and preview URLs, on top of Workers and Containers.\n\nThe distinction from a plain container is trust. A container image you built is a known runtime executing known commands. A sandbox is for the case where a model writes a script and something has to run it — with an isolated filesystem, a process boundary, and no access to the rest of the account.\n\nThis build has that case constantly and currently solves it by not solving it: a model that wants to compute something either asks for a tool row that already exists, or asks the owner's machine to run a shell command. Neither is code execution as a first-class capability. The second is code execution with the blast radius set to \"the owner's laptop\".\n\nA sandbox also gives back something the current arrangement cannot: a preview URL. A model that writes a small web artifact can serve it and hand back a link, instead of writing a file somewhere and describing it.\n\n**Verdict: install, after Containers.** It is the same substrate with a stricter contract, and the stricter contract is what untrusted code needs.\n\n## Code Mode\n\nCode Mode is the one entry in this series that repairs an existing, measured failure rather than adding capability.\n\nThe failure: this build exposes roughly nine hundred tool rows through a single stringly-typed dispatch surface. A model working through that surface spends most of its budget discovering contracts — what arguments does this row take, what does it return, what does the pipe delimiter do to a JSON payload. Measured on the `misc` agent, roughly fourteen of twenty calls in a session went to discovery rather than to work.\n\nCode Mode inverts the loop. Instead of the model calling tools one at a time and reading each result, the tool surface is projected as a typed API, the model writes TypeScript against it, and that code runs in a sandbox with the results coming back once. Discovery happens at code-generation time, against types, rather than at runtime against error messages.\n\nTwo things about this build make the fit unusually good.\n\nFirst, the tool surface is already machine-described. Every directory row has a description and a `when_to_use`, by law. That is the raw material a typed API is generated from, and it already exists.\n\nSecond, the failure this fixes is documented as a tool-surface defect rather than an agent defect. The cheap agent is not bad at its job; it is spending its context on a contract-discovery problem the surface creates. Code Mode is the fix aimed at the layer that permitted it, which is the standard this build holds itself to everywhere else.\n\n**Verdict: install.** This is a repair, not an enhancement.\n\n## The interaction with what is already here\n\nWorth naming, because it is easy to miss: Containers, the Sandbox SDK and Code Mode all sit on Durable Objects, and this build already runs three Durable Object classes in production. The hard part of adopting them — understanding DO identity, lifetime and addressing — is not new work here. It is the same model already in use for the directory and the agent memory.\n\n## Verdicts\n\n| Product | What it replaces here | Verdict |\n| --- | --- | --- |\n| Containers | ~40 CLI rows executing on the owner's laptop | **install** |\n| Sandbox SDK | Model-written code run by a shell command on that laptop | **install** — after Containers |\n| Code Mode | 14 of 20 agent calls spent discovering tool contracts | **install** — this is a repair |\n| Local bridge for screen, clipboard, Chrome, iMessage | Nothing. These are local by definition | **keep local** |\n\nNext: [Part 4 — agents as infrastructure](/a/cloudflare-os-xl-04-agents-as-infrastructure).\n","register":"standard","hero":"https://miscsubjects.com/img/gen/arcads-gpt-image-4057e32c-ad5f-4df7-b1d7-fb0ebc8dcb16.png","hero_brief":"A car engine lifted out of its bay by a workshop hoist and mounted on a rolling engine stand, the empty engine bay visible behind it, tools laid out on the bench. Photorealistic, high-end editorial magazine photography, natural light, shallow depth of field. No readable text, no logos, no people facing camera.","editorial_review":{"headline_subject":"Moving heavy execution off the owner laptop onto Cloudflare Containers","hero_subject":"A car engine hoisted out of its bay and mounted on a rolling stand","visual_action":"The engine suspended clear of the empty bay behind it","rationale":"The part is about lifting the workload out of the machine it currently sits inside, which is literally what the image shows.","inspected":true,"inspection_note":"A V-configuration engine on a red hoist and stand, the stripped engine bay of the car visible behind it, tools on the bench. The removal is the visible action.","hero_brief":"A car engine lifted out of its bay by a workshop hoist and mounted on a rolling engine stand, the empty engine bay visible behind it, tools laid out on the bench. Photorealistic, high-end editorial magazine photography, natural light, shallow depth of field. No readable text, no logos, no people facing camera."},"tags":["cloudflare","containers","sandbox","agents","tooling"],"category":"systems","style":{},"claims":[{"id":"c1","text":"Around forty tool rows in this build execute through a bridge process on the owner Mac, so a third of the build capability is offline whenever that machine is.","tier":"observational","source_ids":[],"why_material":"It is the largest single point of failure in the running system."},{"id":"c2","text":"Cloudflare Containers run alongside Workers for resource-intensive workloads, custom runtimes and existing container images, and each instance is addressed through a Durable Object.","tier":"definition","source_ids":["s-containers"],"why_material":"The build already runs three Durable Object classes, so the addressing model is not new work here."},{"id":"c3","text":"The CLI rows split cleanly into pure transformations, which belong in a container image, and genuinely local capabilities such as the screen, the clipboard, the logged-in browser and the message history.","tier":"expert","source_ids":[],"why_material":"That split is worth making in the directory regardless of whether a container is ever built."},{"id":"c4","text":"The Sandbox SDK provides isolated code execution environments with a filesystem, processes and preview URLs on top of Workers and Containers.","tier":"definition","source_ids":["s-sandbox"],"why_material":"Model-written code currently runs as a shell command on the owner laptop, with that blast radius."},{"id":"c5","text":"A cheap agent working through this build stringly-typed dispatch surface spent roughly fourteen of twenty calls discovering tool contracts rather than doing work.","tier":"observational","source_ids":[],"why_material":"It identifies the defect as a tool-surface property rather than an agent weakness."},{"id":"c6","text":"Code Mode replaces one-call-at-a-time tool use with generated TypeScript executed in a sandbox, so contract discovery happens once at code-generation time against types.","tier":"definition","source_ids":["s-wfp"],"why_material":"Every directory row already carries a description and a when-to-use field, which is the raw material for the generated API."}],"sources":[{"id":"s-containers","type":"documentation","url":"https://developers.cloudflare.com/containers/","title":"Cloudflare Containers documentation","quote":"Run serverless containers alongside Workers to handle resource-intensive workloads, custom runtimes, and existing container images on Cloudflare."},{"id":"s-sandbox","type":"documentation","url":"https://developers.cloudflare.com/sandbox/","title":"Cloudflare Sandbox SDK documentation","quote":"Build secure, isolated code execution environments powered by Cloudflare Workers and Containers."},{"id":"s-wfp","type":"documentation","url":"https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/","title":"Workers for Platforms documentation","quote":"Run untrusted code from your customers or AI in secure, isolated sandboxes on Cloudflare's global network."}],"prov":{"model":"Opus 5 (Claude Code)","action":"write"}}