Skip to main content
@struktoai/mirage-cloudflare runs a workspace inside a Worker: the shell and its commands, plus python3 on Monty when the workspace declares a Monty machine. Nothing else needs to start.

Install

wrangler.toml
  • nodejs_compat gives Mirage Node’s buffer, crypto, path, process and util.
  • no_handle_cross_request_promise_resolution lets a later request finish work an earlier one started, which the server API needs.
  • The alias hands ssh2 a stub for the native cpu-features addon, which a Worker cannot load.

Run a workspace

src/worker.ts
  • python3 stops after the line’s time limit (exit 124) or 30 seconds, so a runaway loop cannot block the Worker.
  • node is refused: QuickJS would block the Worker until Cloudflare’s CPU limit.
  • Import other core modules by subpath, such as @struktoai/mirage-core/vfs/registry. The package root pulls in Pyodide, which a Worker bundle cannot resolve.

Serve the server API

createApp answers the HTTP routes, MCP and RPC as the server does, over the workspaces the isolate holds:
src/worker.ts
A Worker’s URL is public, so it serves nothing without a token or a JWT issuer, set through the server’s MIRAGE_AUTH_* and MIRAGE_JWT_* variables:
wrangler.toml
/v1/workspaces/:id/codex-exec serves Codex’s exec-server over a WebSocket, so codex exec-server forward runs its tools in a workspace on the Worker.

Keep files and sessions

A Worker’s memory goes with its isolate. To keep files and sessions, store them in SQL: SqlVFS over a Durable Object’s storage or a D1 database, and SqlWorkspaceStateStore over the same driver for each session’s directory, variables, functions, jobs and history. Inside your Durable Object:
daemonId set to the Durable Object’s id lets a woken Durable Object take its workspace back at once. A Durable Object per workspace gives each workspace its own database, but not its own memory: Cloudflare may run several of one class in one isolate, sharing its 128 MB.

Secrets

A pointer reads aws-sm and 1password in a Worker as on the server. There is no env source. Read secrets from the Worker’s env bindings in your code and pass them into the source’s config.
aws-sm is registered when the package loads. The Worker signs each request itself and has no credentials file or default chain, so the source’s config gives region, aws_access_key_id and aws_secret_access_key, with aws_session_token for temporary keys. aws_profile is refused.
1Password’s SDK core is about 13 MiB of WebAssembly, so it is its own import. Install the SDK version the package is built against, alias its core to the package’s build, and minify to stay under Cloudflare’s 64 MiB limit:
wrangler.toml
src/worker.ts
The token is the source config’s token, or OP_SERVICE_ACCOUNT_TOKEN among the Worker’s secrets.

VFS and CLIs

The supported VFS and supported CLIs tables show which run on Cloudflare. On Workers, object store VFS run without proxy, Redis is reached through Cloudflare’s connect(), and the mcp and search CLIs also run.

Limits

  • An isolate has 128 MB and no disk, shared by every workspace in it. Set max_memory on each workspace, so a large write fails with Disk quota exceeded before the isolate runs out.
  • The server API’s workspaces live in one isolate’s memory: a request routed to another isolate does not see them, and eviction drops them. store.type must be ram; a workspace built in code keeps its state in SQL, as above.
  • Network rules match host names only. A denied_domains entry that is an IP address or range is refused. The cloud-metadata block in jwt mode catches only requests made to the IP itself.
  • Node server only: SSH, FUSE, policy or script files given by path, and runtimes or CLIs loaded by a source:Class reference.