@cloudflare/sandbox 0.0.0-c0d9d33 → 0.0.0-c2e3384

package/README.md

@@ -1,65 +1,169 @@
-## @cloudflare/sandbox
+<img width="1362" height="450" alt="Image" src="https://github.com/user-attachments/assets/6f770ae3-0a14-4d2b-9aed-a304ee5446c5" />
 
-> **⚠️ Experimental** - This library is currently experimental and we're actively seeking feedback. Please try it out and let us know what you think!
+# Cloudflare Sandbox SDK
 
-A library to spin up a sandboxed environment.
+[![npm version](https://img.shields.io/npm/v/@cloudflare/sandbox.svg)](https://www.npmjs.com/package/@cloudflare/sandbox)
 
-First, setup your wrangler.json to use the sandbox:
+**Build secure, isolated code execution environments on Cloudflare.**
 
-```jsonc
-{
-  // ...
-  "containers": [
-    {
-      "class_name": "Sandbox",
-      "image": "./node_modules/@cloudflare/sandbox/Dockerfile",
-      "name": "sandbox"
-    }
-  ],
-  "durable_objects": {
-    "bindings": [
-      {
-        "class_name": "Sandbox",
-        "name": "Sandbox"
-      }
-    ]
-  },
-  "migrations": [
-    {
-      "new_sqlite_classes": ["Sandbox"],
-      "tag": "v1"
-    }
-  ]
-}
+The Sandbox SDK lets you run untrusted code safely in isolated containers. Execute commands, manage files, run background processes, and expose services — all from your Workers applications.
+
+Perfect for AI code execution, interactive development environments, data analysis platforms, CI/CD systems, and any application that needs secure code execution at the edge.
+
+## Getting Started
+
+### Prerequisites
+
+1. Install [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (version 16.17.0 or later)
+2. Ensure Docker is running locally
+3. For deploying to production, sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages)
+
+### 1. Create a new project
+
+Create a new Sandbox SDK project using the minimal template:
+
+```bash
+npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
+cd my-sandbox
 ```
 
-Then, export the Sandbox class in your worker:
+### 2. Test locally
 
-```ts
-export { Sandbox } from "@cloudflare/sandbox";
+Start the development server:
+
+```bash
+npm run dev
 ```
 
-You can then use the Sandbox class in your worker:
+> **Note:** First run builds the Docker container (2-3 minutes). Subsequent runs are much faster.
+
+Test the endpoints:
+
+```bash
+# Execute Python code
+curl http://localhost:8787/run
+
+# File operations
+curl http://localhost:8787/file
+```
 
-```ts
-import { getSandbox } from "@cloudflare/sandbox";
+### 3. Deploy to production
+
+Deploy your Worker and container:
+
+```bash
+npx wrangler deploy
+```
+
+> **Wait for provisioning:** After first deployment, wait 2-3 minutes before making requests.
+
+**📖 [View the complete getting started guide](https://developers.cloudflare.com/sandbox/get-started/)** for detailed instructions and explanations.
+
+## Quick API Example
+
+```typescript
+import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';
+
+export { Sandbox } from '@cloudflare/sandbox';
+
+type Env = {
+  Sandbox: DurableObjectNamespace<Sandbox>;
+};
 
 export default {
-  async fetch(request: Request, env: Env) {
-    const sandbox = getSandbox(env.Sandbox, "my-sandbox");
-    return sandbox.exec("ls", ["-la"]);
-  },
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Required for preview URLs
+    const proxyResponse = await proxyToSandbox(request, env);
+    if (proxyResponse) return proxyResponse;
+
+    const url = new URL(request.url);
+    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
+
+    // Execute Python code
+    if (url.pathname === '/run') {
+      const result = await sandbox.exec('python3 -c "print(2 + 2)"');
+      return Response.json({ output: result.stdout, success: result.success });
+    }
+
+    // Work with files
+    if (url.pathname === '/file') {
+      await sandbox.writeFile('/workspace/hello.txt', 'Hello, Sandbox!');
+      const file = await sandbox.readFile('/workspace/hello.txt');
+      return Response.json({ content: file.content });
+    }
+
+    return new Response('Try /run or /file');
+  }
 };
 ```
 
-### Methods:
-
-- `exec(command: string, args: string[], options?: { stream?: boolean })`: Execute a command in the sandbox.
-- `gitCheckout(repoUrl: string, options: { branch?: string; targetDir?: string; stream?: boolean })`: Checkout a git repository in the sandbox.
-- `mkdir(path: string, options: { recursive?: boolean; stream?: boolean })`: Create a directory in the sandbox.
-- `writeFile(path: string, content: string, options: { encoding?: string; stream?: boolean })`: Write content to a file in the sandbox.
-- `readFile(path: string, options: { encoding?: string; stream?: boolean })`: Read content from a file in the sandbox.
-- `deleteFile(path: string, options?: { stream?: boolean })`: Delete a file from the sandbox.
-- `renameFile(oldPath: string, newPath: string, options?: { stream?: boolean })`: Rename a file in the sandbox.
-- `moveFile(sourcePath: string, destinationPath: string, options?: { stream?: boolean })`: Move a file from one location to another in the sandbox.
-- `ping()`: Ping the sandbox.
+## Documentation
+
+**📖 [Full Documentation](https://developers.cloudflare.com/sandbox/)**
+
+- [Get Started Guide](https://developers.cloudflare.com/sandbox/get-started/) - Step-by-step tutorial
+- [API Reference](https://developers.cloudflare.com/sandbox/api/) - Complete API docs
+- [Guides](https://developers.cloudflare.com/sandbox/guides/) - Execute commands, manage files, expose services
+- [Examples](https://developers.cloudflare.com/sandbox/tutorials/) - AI agents, data analysis, CI/CD pipelines
+
+## Key Features
+
+- **Secure Isolation** - Each sandbox runs in its own container
+- **Edge-Native** - Runs on Cloudflare's global network
+- **Code Interpreter** - Execute Python and JavaScript with rich outputs
+- **File System Access** - Read, write, and manage files
+- **Command Execution** - Run any command with streaming support
+- **Preview URLs** - Expose services with public URLs
+- **Git Integration** - Clone repositories directly
+
+## Contributing
+
+We welcome contributions from the community! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on:
+
+- Setting up your development environment
+- Creating pull requests
+- Code style and testing requirements
+
+## Development
+
+This repository contains the SDK source code. Quick start:
+
+```bash
+# Clone the repo
+git clone https://github.com/cloudflare/sandbox-sdk
+cd sandbox-sdk
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build the project
+npm run build
+
+# Type checking and linting
+npm run check
+```
+
+## Examples
+
+See the [examples directory](./examples) for complete working examples:
+
+- [Minimal](./examples/minimal) - Basic sandbox setup
+- [Code Interpreter](./examples/code-interpreter) - Use sandbox as an interpreter tool with gpt-oss
+
+## Status
+
+**Beta** - The SDK is in active development. APIs may change before v1.0.
+
+## License
+
+[MIT License](LICENSE)
+
+## Links
+
+- [Documentation](https://developers.cloudflare.com/sandbox/)
+- [GitHub Issues](https://github.com/cloudflare/sandbox-sdk/issues)
+- [Developer Discord](https://discord.cloudflare.com)
+- [Cloudflare Developers](https://twitter.com/CloudflareDev)