> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare Quickstart

> Run Mirage workspaces and the Mirage server API on Cloudflare Workers with @struktoai/mirage-cloudflare.

`@struktoai/mirage-cloudflare` runs a workspace inside a Worker: the shell and
its commands, plus `python3` on [Monty](https://docs.mirage.strukto.ai/typescript/runtime/monty.md) when the
workspace declares a Monty machine. Nothing else needs to start.

## Install

```bash theme={null}
npm install @struktoai/mirage-cloudflare
npm install -D wrangler
```

```toml wrangler.toml theme={null}
name = "mirage"
main = "src/worker.ts"
compatibility_date = "2026-10-01"
compatibility_flags = ["nodejs_compat", "no_handle_cross_request_promise_resolution"]

[alias]
"cpu-features" = "@struktoai/mirage-cloudflare/cpu_features"
```

* `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

```ts src/worker.ts theme={null}
import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-cloudflare'

export default {
  async fetch(request: Request): Promise<Response> {
    const { command } = (await request.json()) as { command: string }
    const ws = new Workspace(
      { '/data': new RAMVFS() },
      {
        mode: MountMode.EXEC,
        machines: { py: { provider: 'in_process', runtime: 'monty' } },
        maxMemory: '32MB',
      },
    )
    try {
      const result = await ws.shell(command)
      return Response.json({ exit: result.exitCode, stdout: result.stdoutText })
    } finally {
      await ws.close()
    }
  },
}
```

```bash theme={null}
npx wrangler dev
curl -s localhost:8787 -d '{"command": "seq 1 100 | sort -rn | head -3"}'
```

```json theme={null}
{"exit":0,"stdout":"100\n99\n98\n"}
```

* `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](https://docs.mirage.strukto.ai/home/access/http.md) routes, [MCP](https://docs.mirage.strukto.ai/home/access/mcp.md)
and [RPC](https://docs.mirage.strukto.ai/home/access/rpc.md) as the [server](https://docs.mirage.strukto.ai/typescript/access/server.md) does,
over the workspaces the isolate holds:

```ts src/worker.ts theme={null}
import { createApp } from '@struktoai/mirage-cloudflare'

export default createApp({ maxWorkspaces: 8 })
```

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](https://docs.mirage.strukto.ai/home/access/http.md#configure-authentication):

```toml wrangler.toml theme={null}
[vars]
MIRAGE_AUTH_MODE = "token"
```

```bash theme={null}
export MIRAGE_AUTH_TOKEN=<token>
npx wrangler secret put MIRAGE_AUTH_TOKEN
curl -s localhost:8787/v1/workspaces -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"id": "demo", "config": {"mode": "exec", "mounts": {"/": {"vfs": "ram"}}, "machines": {"py": {"provider": "in_process", "runtime": "monty"}}}}'
curl -s localhost:8787/v1/workspaces/demo/shell -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN" \
  -H 'content-type: application/json' -d '{"command": "python3 -c \"print(6 * 7)\""}'
```

`/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.

> [accordion] createApp options
>
> | Option | Meaning |
> | - | - |
> | `auth` | An `AuthConfig` in place of the variables: `{ mode: 'token', bearerToken }` or `{ mode: 'jwt', jwt }`. |
> | `maxWorkspaces` | The most workspaces the isolate holds at once. A create past it answers 503. |
> | `maxSessions` | The most sessions each workspace holds, `4` unless set. A new session past it answers 429. |
> | `maxMemory` | The most any workspace's `max_memory` reaches, as a [size](https://docs.mirage.strukto.ai/home/configuration/workspace.md#sizes). |
> | `maxProcesses` | The most any session's `processes.max` reaches. |
> | `maxLineSeconds` | The most seconds any line runs, whatever a config or profile sets. |
> | `maxEnv` | The most any workspace's `max_env` reaches, as a [size](https://docs.mirage.strukto.ai/home/configuration/workspace.md#sizes). |
> | `policies` | The server's own [policies](https://docs.mirage.strukto.ai/home/access/http.md#server-policies). |
> | `snapshotStore` | An `S3Config`: the store a snapshot request may name a key in. |

## Keep files and sessions

A Worker's memory goes with its isolate. To keep files and sessions, store
them in SQL: [`SqlVFS`](https://docs.mirage.strukto.ai/typescript/vfs/sql) 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:

```ts theme={null}
import { DurableObjectSqlDriver, SqlVFS, SqlWorkspaceStateStore, Workspace } from '@struktoai/mirage-cloudflare'

const driver = new DurableObjectSqlDriver(this.ctx.storage)
const ws = new Workspace(
  { '/work': new SqlVFS(driver) },
  {
    workspaceId: 'w1',
    store: new SqlWorkspaceStateStore(driver),
    ownsStore: true,
    daemonId: this.ctx.id.toString(),
  },
)
```

`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](https://docs.mirage.strukto.ai/home/service-credentials.md) 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.

> [accordion] 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.

> [accordion] 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:
>
> ```bash theme={null}
> npm install @1password/sdk@0.5.0
> ```
>
> ```toml wrangler.toml theme={null}
> minify = true
>
> [alias]
> "cpu-features" = "@struktoai/mirage-cloudflare/cpu_features"
> "@1password/sdk-core" = "@struktoai/mirage-cloudflare/onepassword_core"
> ```
>
> ```ts src/worker.ts theme={null}
> import '@struktoai/mirage-cloudflare/onepassword'
> ```
>
> The token is the source config's `token`, or `OP_SERVICE_ACCOUNT_TOKEN`
> among the Worker's secrets.

## VFS and CLIs

The [supported VFS](https://docs.mirage.strukto.ai/home/setup/vfs.md#supported-vfs) and [supported CLIs](https://docs.mirage.strukto.ai/home/setup/clis.md#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](#keep-files-and-sessions).
* 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.