secondsky/claude-skills / plugins/cloudflare-sandbox/skills/cloudflare-sandbox
cloudflare-sandbox
VerifiedCloudflare Sandboxes SDK for secure code execution in Linux containers at edge. Use for untrusted code, Python/Node.js scripts, AI code interpreters, git operations.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.3 KB |
| assets/example-template.txt | markdown | 416 B |
| references/advanced.md | markdown | 4.4 KB |
| references/api-reference.md | markdown | 3.0 KB |
| references/common-errors.md | markdown | 9.5 KB |
| references/example-reference.md | markdown | 760 B |
| references/naming-strategies.md | markdown | 8.5 KB |
| references/patterns.md | markdown | 5.0 KB |
| references/persistence-guide.md | markdown | 8.0 KB |
| references/session-management.md | markdown | 9.9 KB |
| scripts/example-script.shexecutable | script | 302 B |
| scripts/setup-sandbox-binding.shexecutable | script | 3.6 KB |
| scripts/test-sandbox.ts | script | 6.8 KB |
| templates/basic-executor.ts | script | 3.2 KB |
| templates/chat-agent.ts | script | 6.3 KB |
| templates/ci-cd.ts | script | 7.5 KB |
| templates/workspace.ts | script | 10.2 KB |
templates/workspace.ts
View on GitHub/**
* Cloudflare Sandbox - Persistent User Workspace Pattern
*
* Use Case: Interactive notebooks, IDEs, development environments with file persistence
*
* Features:
* - Per-user sandbox (persists while active ~10 min)
* - Automatic backup to R2 for long-term persistence
* - Restore from R2 on cold starts
* - File operations (read, write, list, delete)
* - Session management for command execution
*
* Pattern: User Sandbox + R2 Backup + Auto-Restore
*/
import { getSandbox, type Sandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
type Env = {
Sandbox: DurableObjectNamespace<Sandbox>;
R2: R2Bucket; // For backing up workspace files
KV: KVNamespace; // For storing workspace metadata
};
type WorkspaceRequest =
| { action: 'execute'; userId: string; command: string; timeout?: number }
| { action: 'writeFile'; userId: string; path: string; content: string }
| { action: 'readFile'; userId: string; path: string }
| { action: 'listFiles'; userId: string; directory?: string }
| { action: 'deleteFile'; userId: string; path: string }
| { action: 'backup'; userId: string }
| { action: 'restore'; userId: string }
| { action: 'reset'; userId: string };
type WorkspaceResponse = {
success: boolean;
data?: any;
error?: string;
};
export default {
async fetch(request: Request, env: Env): Promise<Response> {
if (request.method !== 'POST') {
return new Response('Method not allowed', { status: 405 });
}
try {
const body = await request.json() as WorkspaceRequest;
// Validate input
if (!body.userId) {
return Response.json({
success: false,
error: 'userId is required'
}, { status: 400 });
}
// Get user's sandbox
const sandboxId = `workspace-${body.userId}`;
const sandbox = getSandbox(env.Sandbox, sandboxId);
// Handle different actions
switch (body.action) {
case 'execute':
return await handleExecute(sandbox, env, body);
case 'writeFile':
return await handleWriteFile(sandbox, env, body);
case 'readFile':
return await handleReadFile(sandbox, env, body);
case 'listFiles':
return await handleListFiles(sandbox, env, body);
case 'deleteFile':
return await handleDeleteFile(sandbox, env, body);
case 'backup':
return await handleBackup(sandbox, env, body);
case 'restore':
return await handleRestore(sandbox, env, body);
case 'reset':
return await handleReset(sandbox, env, body);
default:
return Response.json({
success: false,
error: 'Invalid action'
}, { status: 400 });
}
} catch (error) {
console.error('Workspace error:', error);
return Response.json({
success: false,
error: error instanceof Error ? error.message : 'Unknown error'
}, { status: 500 });
}
}
};
/**
* Execute command in user's workspace
*/
async function handleExecute(
sandbox: Sandbox,
env: Env,
body: Extract<WorkspaceRequest, { action: 'execute' }>
): Promise<Response> {
// Get or create session
const sessionKey = `session:${body.userId}`;
let sessionId = await env.KV.get(sessionKey);
if (!sessionId) {
sessionId = await sandbox.createSession();
await env.KV.put(sessionKey, sessionId, { expirationTtl: 3600 });
}
// Check if workspace needs restoration
await ensureWorkspaceRestored(sandbox, env, body.userId);
// Execute command
const result = await sandbox.exec(body.command, {
session: sessionId,
timeout: body.timeout || 30000,
cwd: '/workspace'
});
if (!result.success) {
return Response.json({
success: false,
error: result.stderr,
data: { exitCode: result.exitCode }
}, { status: 400 });
}
return Response.json({
success: true,
data: {
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.exitCode
}
});
}
/**
* Write file to user's workspace
*/
async function handleWriteFile(
sandbox: Sandbox,
env: Env,
body: Extract<WorkspaceRequest, { action: 'writeFile' }>
): Promise<Response> {
await ensureWorkspaceRestored(sandbox, env, body.userId);
await sandbox.writeFile(`/workspace/${body.path}`, body.content);
// Auto-backup after write
await backupFile(sandbox, env, body.userId, body.path);
return Response.json({
success: true,
data: { path: body.path, size: body.content.length }
});
}
/**
* Read file from user's workspace
*/
async function handleReadFile(
sandbox: Sandbox,
env: Env,
body: Extract<WorkspaceRequest, { action: 'readFile' }>
): Promise<Response> {
await ensureWorkspaceRestored(sandbox, env, body.userId);
try {
const content = await sandbox.readFile(`/workspace/${body.path}`);
return Response.json({
success: true,
data: { path: body.path, content }
});
} catch (error) {
return Response.json({
success: false,
error: `File not found: ${body.path}`
}, { status: 404 });
}
}
/**
* List files in user's workspace
*/
async function handleListFiles(
sandbox: Sandbox,
env: Env,
body: Extract<WorkspaceRequest, { action: 'listFiles' }>
): Promise<Response> {
await ensureWorkspaceRestored(sandbox, env, body.userId);
const directory = body.directory || '';
const result = await sandbox.exec(`find ${directory} -type f`, {
cwd: '/workspace',
timeout: 10000
});
if (!result.success) {
return Response.json({
success: false,
error: result.stderr
}, { status: 400 });
}
const files = result.stdout
.split('\n')
.filter(f => f.trim())
.map(f => f.replace(/^\.\//, ''));
return Response.json({
success: true,
data: { files }
});
}
/**
* Delete file from user's workspace
*/
async function handleDeleteFile(
sandbox: Sandbox,
env: Env,
body: Extract<WorkspaceRequest, { action: 'deleteFile' }>
): Promise<Response> {
await ensureWorkspaceRestored(sandbox, env, body.userId);
await sandbox.rm(`/workspace/${body.path}`);
// Delete from R2 backup
await env.R2.delete(`workspaces/${body.userId}/${body.path}`);
return Response.json({
success: true,
data: { deleted: body.path }
});
}
/**
* Manually backup entire workspace
*/
async function handleBackup(
sandbox: Sandbox,
env: Env,
body: Extract<WorkspaceRequest, { action: 'backup' }>
): Promise<Response> {
const result = await sandbox.exec('find . -type f', {
cwd: '/workspace',
timeout: 10000
});
if (!result.success) {
return Response.json({
success: false,
error: 'Failed to list files'
}, { status: 500 });
}
const files = result.stdout.split('\n').filter(f => f.trim());
let backedUp = 0;
for (const file of files) {
const cleanPath = file.replace(/^\.\//, '');
try {
await backupFile(sandbox, env, body.userId, cleanPath);
backedUp++;
} catch (error) {
console.error(`Failed to backup ${cleanPath}:`, error);
}
}
return Response.json({
success: true,
data: { filesBackedUp: backedUp, totalFiles: files.length }
});
}
/**
* Restore workspace from R2
*/
async function handleRestore(
sandbox: Sandbox,
env: Env,
body: Extract<WorkspaceRequest, { action: 'restore' }>
): Promise<Response> {
const restored = await restoreWorkspace(sandbox, env, body.userId);
return Response.json({
success: true,
data: { filesRestored: restored }
});
}
/**
* Reset user's workspace
*/
async function handleReset(
sandbox: Sandbox,
env: Env,
body: Extract<WorkspaceRequest, { action: 'reset' }>
): Promise<Response> {
// Delete all files from R2
const listed = await env.R2.list({ prefix: `workspaces/${body.userId}/` });
for (const obj of listed.objects) {
await env.R2.delete(obj.key);
}
// Destroy sandbox
await sandbox.destroy();
// Clear session
await env.KV.delete(`session:${body.userId}`);
await env.KV.delete(`workspace:restored:${body.userId}`);
return Response.json({
success: true,
data: { reset: true }
});
}
/**
* Helper: Ensure workspace is restored from R2 (handles cold starts)
*/
async function ensureWorkspaceRestored(
sandbox: Sandbox,
env: Env,
userId: string
): Promise<void> {
const restoredKey = `workspace:restored:${userId}`;
const isRestored = await env.KV.get(restoredKey);
if (!isRestored) {
await restoreWorkspace(sandbox, env, userId);
await env.KV.put(restoredKey, 'true', { expirationTtl: 600 }); // 10 min TTL
}
}
/**
* Helper: Restore all files from R2
*/
async function restoreWorkspace(
sandbox: Sandbox,
env: Env,
userId: string
): Promise<number> {
const listed = await env.R2.list({ prefix: `workspaces/${userId}/` });
let restored = 0;
for (const obj of listed.objects) {
const file = await env.R2.get(obj.key);
if (!file) continue;
const relativePath = obj.key.replace(`workspaces/${userId}/`, '');
const content = await file.text();
await sandbox.writeFile(`/workspace/${relativePath}`, content);
restored++;
}
return restored;
}
/**
* Helper: Backup single file to R2
*/
async function backupFile(
sandbox: Sandbox,
env: Env,
userId: string,
path: string
): Promise<void> {
const content = await sandbox.readFile(`/workspace/${path}`);
await env.R2.put(`workspaces/${userId}/${path}`, content, {
customMetadata: {
userId,
lastModified: new Date().toISOString()
}
});
}
/**
* Example Usage:
*
* 1. Create file:
* POST / { "action": "writeFile", "userId": "user123", "path": "hello.py", "content": "print('hello')" }
*
* 2. Execute code:
* POST / { "action": "execute", "userId": "user123", "command": "python hello.py" }
* Response: { "success": true, "data": { "stdout": "hello\n", ... } }
*
* 3. List files:
* POST / { "action": "listFiles", "userId": "user123" }
* Response: { "success": true, "data": { "files": ["hello.py"] } }
*
* 4. Backup (automatic on write, or manual):
* POST / { "action": "backup", "userId": "user123" }
*
* 5. After container goes idle, workspace auto-restores from R2 on next request
*/
/**
* wrangler.jsonc additions required:
*
* {
* "r2_buckets": [{ "binding": "R2", "bucket_name": "user-workspaces" }],
* "kv_namespaces": [{ "binding": "KV", "id": "your-kv-id" }]
* }
*/
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |