# Cloudflare OS: running real code

slug: cloudflare-os-xl-03-running-real-code · https://miscsubjects.com/a/cloudflare-os-xl-03-running-real-code · category: systems · tags: cloudflare, containers, sandbox, agents, tooling · updated 2026-08-06T03:28:34.029Z

*Part 3 of [Cloudflare OS XL](/a/cloudflare-os-xl), an inventory of the Cloudflare platform this build does not have installed.*

There 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.

The 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.

This 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.

## Containers

Containers 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.

The 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.

```toml
[[containers]]
class_name = "ToolRunner"
image = "./Dockerfile"
max_instances = 5
```

The 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.

Splitting 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.

**Verdict: install.** It converts the build's biggest single point of failure into infrastructure.

## The Sandbox SDK

The 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.

The 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.

This 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".

A 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.

**Verdict: install, after Containers.** It is the same substrate with a stricter contract, and the stricter contract is what untrusted code needs.

## Code Mode

Code Mode is the one entry in this series that repairs an existing, measured failure rather than adding capability.

The 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.

Code 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.

Two things about this build make the fit unusually good.

First, 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.

Second, 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.

**Verdict: install.** This is a repair, not an enhancement.

## The interaction with what is already here

Worth 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.

## Verdicts

| Product | What it replaces here | Verdict |
| --- | --- | --- |
| Containers | ~40 CLI rows executing on the owner's laptop | **install** |
| Sandbox SDK | Model-written code run by a shell command on that laptop | **install** — after Containers |
| Code Mode | 14 of 20 agent calls spent discovering tool contracts | **install** — this is a repair |
| Local bridge for screen, clipboard, Chrome, iMessage | Nothing. These are local by definition | **keep local** |

Next: [Part 4 — agents as infrastructure](/a/cloudflare-os-xl-04-agents-as-infrastructure).


## Sources

1. Cloudflare Containers documentation — https://developers.cloudflare.com/containers/
2. Cloudflare Sandbox SDK documentation — https://developers.cloudflare.com/sandbox/
3. Workers for Platforms documentation — https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/