AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

references/sandbox/gotchas.md

Gotchas & Best Practices

Common Errors

"Container running indefinitely"

Cause: keepAlive: true without calling destroy() Solution: Always call destroy() when done with keepAlive containers

const sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true });
try {
  const result = await sandbox.exec('python script.py');
  return result.stdout;
} finally {
  await sandbox.destroy();  // REQUIRED to free resources
}

"CONTAINER_NOT_READY"

Cause: Container still provisioning (first request or after sleep) Solution: Retry after 2-3s

async function execWithRetry(sandbox, cmd) {
  for (let i = 0; i < 3; i++) {
    try {
      return await sandbox.exec(cmd);
    } catch (e) {
      if (e.code === 'CONTAINER_NOT_READY') {
        await new Promise(r => setTimeout(r, 2000));
        continue;
      }
      throw e;
    }
  }
}

"Connection refused: container port not found"

Cause: Missing EXPOSE directive in Dockerfile Solution: Add EXPOSE <port> to Dockerfile (only needed for wrangler dev, production auto-exposes)

"Preview URLs not working"

Cause: Custom domain not configured, wildcard DNS missing, normalizeId not set, or proxyToSandbox() not called Solution: Check:

  1. Custom domain configured? (not .workers.dev)
  2. Wildcard DNS set up? (*.domain.com → worker.domain.com)
  3. normalizeId: true in getSandbox?
  4. proxyToSandbox() called first in fetch?

"Slow first request"

Cause: Cold start (container provisioning) Solution:

  • Use sleepAfter instead of creating new sandboxes
  • Pre-warm with cron triggers
  • Set keepAlive: true for critical sandboxes

"File not persisting"

Cause: Files in /tmp or other ephemeral paths Solution: Use /workspace for persistent files

"Bucket mounting doesn't work locally"

Cause: Bucket mounting requires FUSE, not available in wrangler dev Solution: Test bucket mounting in production only. Use mock data locally.

"Different normalizeId = different sandbox"

Cause: Changing normalizeId option changes Durable Object ID Solution: Set normalizeId consistently. normalizeId: true lowercases the ID.

// These create DIFFERENT sandboxes:
getSandbox(env.Sandbox, 'MyApp');              // DO ID: hash('MyApp')
getSandbox(env.Sandbox, 'MyApp', { normalizeId: true });  // DO ID: hash('myapp')

"Code context variables disappeared"

Cause: Container restart clears code context state Solution: Code contexts are ephemeral. Recreate context after container sleep/wake.

Performance Optimization

Sandbox ID Strategy

// ❌ BAD: New sandbox every time (slow)
const sandbox = getSandbox(env.Sandbox, `user-${Date.now()}`);

// ✅ GOOD: Reuse per user
const sandbox = getSandbox(env.Sandbox, `user-${userId}`);

Sleep & Traffic Config

// Cost-optimized
getSandbox(env.Sandbox, 'id', { sleepAfter: '30m', keepAlive: false });

// Always-on (requires destroy())
getSandbox(env.Sandbox, 'id', { keepAlive: true });
// High traffic: increase max_instances
{ "containers": [{ "class_name": "Sandbox", "max_instances": 50 }] }

Security Best Practices

Sandbox Isolation

  • Each sandbox = isolated container (filesystem, network, processes)
  • Use unique sandbox IDs per tenant for multi-tenant apps
  • Sandboxes cannot communicate directly

Input Validation

// ❌ DANGEROUS: Command injection
const result = await sandbox.exec(`python3 -c "${userCode}"`);

// ✅ SAFE: Write to file, execute file
await sandbox.writeFile('/workspace/user_code.py', userCode);
const result = await sandbox.exec('python3 /workspace/user_code.py');

Resource Limits

// Timeout long-running commands
const result = await sandbox.exec('python3 script.py', {
  timeout: 30000  // 30 seconds
});

Secrets Management

// ❌ NEVER hardcode secrets
const token = 'ghp_abc123';

// ✅ Use environment secrets
const token = env.GITHUB_TOKEN;

// Pass to sandbox via exec env
const result = await sandbox.exec('git clone ...', {
  env: { GIT_TOKEN: token }
});

Preview URL Security

Preview URLs include auto-generated tokens:

https://8080-sandbox-abc123def456.yourdomain.com

Token changes on each expose operation, preventing unauthorized access.

Limits

| Resource | Lite | Standard | Heavy | |----------|------|----------|-------| | RAM | 256MB | 512MB | 1GB | | vCPU | 0.5 | 1 | 2 |

| Operation | Default Timeout | Override | |-----------|----------------|----------| | Container provisioning | 30s | SANDBOX_INSTANCE_TIMEOUT_MS | | Port readiness | 90s | SANDBOX_PORT_TIMEOUT_MS | | exec() | 120s | timeout option | | sleepAfter | 10m | sleepAfter option |

Performance:

  • First deploy: 2-3 min for container build
  • Cold start: 2-3s when waking from sleep
  • Bucket mounting: Production only (FUSE not in dev)

Production Guide

See: https://developers.cloudflare.com/sandbox/guides/production-deployment/

Resources