> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/providers/cloudflare.md).

# Cloudflare

Install, configure, and use the Cloudflare provider for ComputeSDK to run sandboxes on Cloudflare's edge network.

{% embed url="<https://www.computesdk.com/benchmarks/sandboxes/cloudflare/>" %}

Cloudflare provider for ComputeSDK - Execute code in secure, isolated sandboxes on Cloudflare's edge network.

## Installation

```bash
npm install @computesdk/cloudflare
```

## Setup

To use the Cloudflare provider in remote mode, deploy the Cloudflare sandbox demo Worker once and connect to it over HTTP.

You can print these setup instructions at any time by running:

```bash
npx @computesdk/cloudflare
```

> **Note:** This command only prints instructions — it does not deploy anything and does not require Docker.

### Step 1: Deploy the sandbox demo Worker

Follow the deployment instructions for the [sandbox demo Worker](https://github.com/cloudflare/containers-demos/tree/main/sandbox).

### Step 2: Set the Worker's API key secret

From the sandbox demo Worker project, set the `SANDBOX_API_KEY` secret:

```bash
npx wrangler secret put SANDBOX_API_KEY
```

### Step 3: Configure your app

Add the Worker URL and the same API key to your `.env` file:

```bash
CLOUDFLARE_SANDBOX_URL=https://sandbox.<your-subdomain>.workers.dev
CLOUDFLARE_SANDBOX_API_KEY=<same value as SANDBOX_API_KEY>
```

These are the only env vars needed at runtime.

## Usage

```typescript
import { cloudflare } from '@computesdk/cloudflare';

const compute = cloudflare({
  sandboxUrl: process.env.CLOUDFLARE_SANDBOX_URL,
  sandboxApiKey: process.env.CLOUDFLARE_SANDBOX_API_KEY,
});

// Create sandbox
const sandbox = await compute.instances.create();

// Run a command
const result = await sandbox.runCommand('echo "Hello from Cloudflare!"');
console.log(result.stdout); // "Hello from Cloudflare!"

// Clean up
await sandbox.destroy();
```

### Run Commands

```typescript
const result = await sandbox.runCommand('ls -la /tmp');
console.log(result.stdout);
```

### Filesystem

```typescript
await sandbox.filesystem.mkdir('/tmp/app/data');
await sandbox.filesystem.writeFile('/tmp/app/config.json', JSON.stringify({ key: 'value' }));
const content = await sandbox.filesystem.readFile('/tmp/app/config.json');

const files = await sandbox.filesystem.readdir('/tmp/app');
const exists = await sandbox.filesystem.exists('/tmp/app/config.json');
await sandbox.filesystem.remove('/tmp/app/temp.txt');
```

### Environment Variables

Pass environment variables at the provider level:

```typescript
const compute = cloudflare({
  sandboxUrl: process.env.CLOUDFLARE_SANDBOX_URL,
  sandboxApiKey: process.env.CLOUDFLARE_SANDBOX_API_KEY,
  envVars: {
    API_KEY: 'your-api-key',
    DATABASE_URL: 'postgresql://localhost:5432/mydb',
  },
});
```

Or per-sandbox at creation time:

```typescript
const sandbox = await compute.instances.create({
  envs: { NODE_ENV: 'production' },
});
```

### Sandbox Size and Image

Choose the size and image of a new sandbox when you create it:

```typescript
const sandbox = await compute.instances.create({
  vcpu: 2,
  memoryMib: 6144,
  diskMb: 12000,
  image: 'builder',
});
```

| Option      | Description                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `vcpu`      | vCPUs of a [custom instance type](https://developers.cloudflare.com/containers/platform/limits/#custom-instance-types) |
| `memoryMib` | Memory of the custom instance type, in MiB                                                                             |
| `diskMb`    | Disk of the custom instance type, in MB                                                                                |
| `image`     | Name of an image declared by the sandbox demo Worker. `builder` has Node.js 24 and common build tools.                 |

Set `vcpu`, `memoryMib`, and `diskMb` together. Without them, the sandbox uses the Worker's default instance type. Without `image`, it uses the Worker's default image.

### Configuration Options

```typescript
interface CloudflareConfig {
  /** URL of the deployed sandbox demo Worker (remote mode) */
  sandboxUrl?: string;
  /** API key for authenticating with the Worker */
  sandboxApiKey?: string;
  /** @deprecated Use sandboxApiKey instead. */
  sandboxSecret?: string;
  /** Durable Object binding to the sandbox demo Worker's Sandbox class (direct mode only) */
  sandboxBinding?: any;
  /** Execution timeout in milliseconds (default 30,000; maximum 900,000) */
  timeout?: number;
  /** Environment variables to pass to sandbox */
  envVars?: Record<string, string>;
}
```

## Direct Mode

A Cloudflare Worker can call the sandbox demo Worker's Durable Object directly instead of using its HTTP API. Add a cross-script Durable Object binding to the Worker that uses ComputeSDK:

```jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "SANDBOX",
        "class_name": "Sandbox",
        "script_name": "sandbox"
      }
    ]
  }
}
```

Pass the binding to the provider:

```typescript
const compute = cloudflare({
  sandboxBinding: env.SANDBOX,
});
```

## Limitations

* Resource limits apply based on your Cloudflare plan
* Some system calls may be restricted in the container environment
* Port forwarding is not supported
* Listing all sandboxes is not supported — use `getById` to reconnect to a specific sandbox


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.computesdk.com/providers/cloudflare.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.