@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_compatgives Mirage Node’sbuffer,crypto,path,processandutil.no_handle_cross_request_promise_resolutionlets a later request finish work an earlier one started, which the server API needs.- The alias hands
ssh2a stub for the nativecpu-featuresaddon, which a Worker cannot load.
Run a workspace
src/worker.ts
python3stops after the line’s time limit (exit 124) or 30 seconds, so a runaway loop cannot block the Worker.nodeis 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
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.
createApp options
createApp options
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 readsaws-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 Secrets Manager
AWS Secrets Manager
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
1Password
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:The token is the source config’s
wrangler.toml
src/worker.ts
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 withoutproxy, 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_memoryon each workspace, so a large write fails withDisk quota exceededbefore 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.typemust beram; a workspace built in code keeps its state in SQL, as above. - Network rules match host names only. A
denied_domainsentry 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:Classreference.