@cloudflare/sandbox 0.0.0-fd5ec7f → 0.0.0-feafd32

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # @cloudflare/sandbox
 
+## 0.3.3
+
+### Patch Changes
+
+- [#83](https://github.com/cloudflare/sandbox-sdk/pull/83) [`eec5bb6`](https://github.com/cloudflare/sandbox-sdk/commit/eec5bb6203dd5d775b4b54e91c26de25eeb767ce) Thanks [@mikenomitch](https://github.com/mikenomitch)! - Bump containers package version
+
+## 0.3.2
+
+### Patch Changes
+
+- [#76](https://github.com/cloudflare/sandbox-sdk/pull/76) [`ef9e320`](https://github.com/cloudflare/sandbox-sdk/commit/ef9e320dcef30e57797fef6ebd9a9383fa9720d9) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Replace Jupyter with lightweight interpreters for >90% faster cold starts for `.runCode` calls, while maintaining full code execution capabilities and rich output support.
+
+## 0.3.1
+
+### Patch Changes
+
+- [#71](https://github.com/cloudflare/sandbox-sdk/pull/71) [`fb3c9c2`](https://github.com/cloudflare/sandbox-sdk/commit/fb3c9c22242d9d4f157c26f547f1e697ef7875f9) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Bump containers package version
+
+- [#70](https://github.com/cloudflare/sandbox-sdk/pull/70) [`e1fa354`](https://github.com/cloudflare/sandbox-sdk/commit/e1fa354ab1bc7b0e89db4901b67028ebf1a93d0a) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Fix escaped quotes in file write operations
+
+- [#68](https://github.com/cloudflare/sandbox-sdk/pull/68) [`69b91d1`](https://github.com/cloudflare/sandbox-sdk/commit/69b91d1a8f6afb63262cc381ea93e94a033ed5e8) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Configurable timeouts via environment variables in isolation.ts
+
+- [#66](https://github.com/cloudflare/sandbox-sdk/pull/66) [`eca93b9`](https://github.com/cloudflare/sandbox-sdk/commit/eca93b97e40fa0d3bd9dc27af2cc214ec355b696) Thanks [@peterp](https://github.com/peterp)! - Determine if the port is specified in the URL.
+
+## 0.3.0
+
+### Minor Changes
+
+- [#59](https://github.com/cloudflare/sandbox-sdk/pull/59) [`b6757f7`](https://github.com/cloudflare/sandbox-sdk/commit/b6757f730c34381d5a70d513944bbf9840f598ab) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Add process isolation for sandbox commands
+
+  Implements PID namespace isolation to protect control plane processes (Jupyter, Bun) from sandboxed code. Commands executed via `exec()` now run in isolated namespaces that cannot see or interact with system processes.
+
+  **Key security improvements:**
+
+  - Control plane processes are hidden from sandboxed commands
+  - Platform secrets in `/proc/1/environ` are inaccessible
+  - Ports 8888 (Jupyter) and 3000 (Bun) are protected from hijacking
+
+  **Breaking changes:**
+
+  1. **Removed `sessionId` parameter**: The `sessionId` parameter has been removed from all methods (`exec()`, `execStream()`, `startProcess()`, etc.). Each sandbox now maintains its own persistent session automatically.
+
+     ```javascript
+     // Before: manual session management
+     await sandbox.exec("cd /app", { sessionId: "my-session" });
+
+     // After: automatic session per sandbox
+     await sandbox.exec("cd /app");
+     ```
+
+  2. **Commands now maintain state**: Commands within the same sandbox now share state (working directory, environment variables, background processes). Previously each command was stateless.
+
+     ```javascript
+     // Before: each exec was independent
+     await sandbox.exec("cd /app");
+     await sandbox.exec("pwd"); // Output: /workspace
+
+     // After: state persists in session
+     await sandbox.exec("cd /app");
+     await sandbox.exec("pwd"); // Output: /app
+     ```
+
+  **Migration guide:**
+
+  - Remove `sessionId` from all method calls - each sandbox maintains its own session
+  - If you need isolated execution contexts within the same sandbox, use `sandbox.createSession()`:
+    ```javascript
+    // Create independent sessions with different environments
+    const buildSession = await sandbox.createSession({
+      name: "build",
+      env: { NODE_ENV: "production" },
+      cwd: "/build",
+    });
+    const testSession = await sandbox.createSession({
+      name: "test",
+      env: { NODE_ENV: "test" },
+      cwd: "/test",
+    });
+    ```
+  - Environment variables set in one command persist to the next
+  - Background processes remain active until explicitly killed
+  - Requires CAP_SYS_ADMIN (available in production, falls back gracefully in dev)
+
+### Patch Changes
+
+- [#62](https://github.com/cloudflare/sandbox-sdk/pull/62) [`4bedc3a`](https://github.com/cloudflare/sandbox-sdk/commit/4bedc3aba347f3d4090a6efe2c9778bac00ce74a) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Fix broken build due to bun lockfile not being used
+
+## 0.2.4
+
+### Patch Changes
+
+- [#57](https://github.com/cloudflare/sandbox-sdk/pull/57) [`12bbd12`](https://github.com/cloudflare/sandbox-sdk/commit/12bbd1229c07ef8c1c0bf58a4235a27938155b08) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Add listFiles method
+
+## 0.2.3
+
+### Patch Changes
+
+- [#53](https://github.com/cloudflare/sandbox-sdk/pull/53) [`c87db11`](https://github.com/cloudflare/sandbox-sdk/commit/c87db117693a86cfb667bf09fb7720d6a6e0524d) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Improve jupyterlab config to speed up startup
+
+## 0.2.2
+
+### Patch Changes
+
+- [#51](https://github.com/cloudflare/sandbox-sdk/pull/51) [`4aceb32`](https://github.com/cloudflare/sandbox-sdk/commit/4aceb3215c836f59afcb88b2b325016b3f623f46) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Handle intermittent interpreter failures and decouple jupyter startup
+
+## 0.2.1
+
+### Patch Changes
+
+- [#49](https://github.com/cloudflare/sandbox-sdk/pull/49) [`d81d2a5`](https://github.com/cloudflare/sandbox-sdk/commit/d81d2a563c9af8947d5444019ed4d6156db563e3) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Implement code interpreter API
+
+## 0.2.0
+
+### Minor Changes
+
+- [#47](https://github.com/cloudflare/sandbox-sdk/pull/47) [`8a93d0c`](https://github.com/cloudflare/sandbox-sdk/commit/8a93d0cae18a25bda6506b8b0a08d9e9eb3bb290) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Change default directory to a clean /workspace
+
+## 0.1.4
+
+### Patch Changes
+
+- [#46](https://github.com/cloudflare/sandbox-sdk/pull/46) [`7de28be`](https://github.com/cloudflare/sandbox-sdk/commit/7de28be482d9634551572d548c7c4b5842df812d) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Update README
+
+- [#44](https://github.com/cloudflare/sandbox-sdk/pull/44) [`215ab49`](https://github.com/cloudflare/sandbox-sdk/commit/215ab494427d7e2a92bb9a25384cb493a221c200) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Update example to use env & cwd
+
+- [#42](https://github.com/cloudflare/sandbox-sdk/pull/42) [`bb72193`](https://github.com/cloudflare/sandbox-sdk/commit/bb72193ad75695979bd1132206f481e91fe37325) Thanks [@jonasnobile](https://github.com/jonasnobile)! - Propagate `cwd` and `env` options in `executeCommand`
+
+- [#27](https://github.com/cloudflare/sandbox-sdk/pull/27) [`fd5ec7f`](https://github.com/cloudflare/sandbox-sdk/commit/fd5ec7f34bc12b06320a89356c4af07801f52d64) Thanks [@threepointone](https://github.com/threepointone)! - remove yarn and pnpm from the image
+
 ## 0.1.3
 
 ### Patch Changes

package/Dockerfile

@@ -31,23 +31,19 @@ RUN apt-get update && apt-get install -y \
     python3.11 \
     python3.11-dev \
     python3-pip \
+    python3.11-venv \
     # Other useful tools
-    sudo \
     ca-certificates \
     gnupg \
     lsb-release \
+    strace \
     && rm -rf /var/lib/apt/lists/*
 
 # Set Python 3.11 as default python3
 RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
 
-# Install Node.js 22 LTS
-# Using the official NodeSource repository setup script
-RUN apt-get update && apt-get install -y ca-certificates curl gnupg \
-    && mkdir -p /etc/apt/keyrings \
-    && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
-    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \
-    && apt-get update \
+# Install Node.js 20 LTS using official NodeSource setup script
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
     && apt-get install -y nodejs \
     && rm -rf /var/lib/apt/lists/*
 
@@ -55,22 +51,52 @@ RUN apt-get update && apt-get install -y ca-certificates curl gnupg \
 COPY --from=bun-source /usr/local/bin/bun /usr/local/bin/bun
 COPY --from=bun-source /usr/local/bin/bunx /usr/local/bin/bunx
 
+# Install essential Python packages for code execution
+RUN pip3 install --no-cache-dir \
+    matplotlib \
+    numpy \
+    pandas \
+    ipython
 
-# Set up working directory
-WORKDIR /app
+# Set up container server directory
+WORKDIR /container-server
 
 # Verify installations
 RUN python3 --version && \
     node --version && \
     npm --version && \
     bun --version
-    
 
-# Copy container source files
+# Copy container source files to server directory
+COPY container_src/package.json container_src/bun.lock ./
+RUN bun install --frozen-lockfile
+
 COPY container_src/ ./
 
-# Expose the application port
+# Compile TypeScript files using the locally installed TypeScript
+RUN npx tsc control-process.ts --outDir . --module commonjs --target es2020 --esModuleInterop --skipLibCheck
+RUN cd runtime/executors/javascript && npx tsc node_executor.ts --module commonjs --target es2020 --esModuleInterop --skipLibCheck
+RUN cd runtime/executors/typescript && npx tsc ts_executor.ts --module commonjs --target es2020 --esModuleInterop --skipLibCheck
+
+# Configure process pool sizes (can be overridden at runtime)
+ENV PYTHON_POOL_MIN_SIZE=3
+ENV PYTHON_POOL_MAX_SIZE=15
+ENV JAVASCRIPT_POOL_MIN_SIZE=3
+ENV JAVASCRIPT_POOL_MAX_SIZE=10
+ENV TYPESCRIPT_POOL_MIN_SIZE=3
+ENV TYPESCRIPT_POOL_MAX_SIZE=10
+
+# Create clean workspace directory for user code
+# Architecture:
+#   /container-server/ - SDK infrastructure (server, executors, dependencies)
+#   /workspace/ - User's clean workspace for their code
+RUN mkdir -p /workspace
+
+# Expose the application port (3000 for control)
 EXPOSE 3000
 
-# Run the application
-CMD ["bun", "index.ts"]
+# Make startup script executable
+RUN chmod +x startup.sh
+
+# Use startup script
+CMD ["./startup.sh"]

package/README.md

@@ -17,6 +17,10 @@
   - [Basic Setup](#basic-setup)
 - [📚 API Reference](#api-reference)
   - [Core Methods](#core-methods)
+- [🧪 Code Interpreter](#code-interpreter)
+  - [Code Execution](#code-execution)
+  - [Rich Outputs](#rich-outputs)
+  - [Output Formats](#output-formats)
 - [🌐 Port Forwarding](#port-forwarding)
   - [Utility Methods](#utility-methods)
 - [💡 Examples](#examples)
@@ -24,6 +28,7 @@
   - [Build and Test Code](#build-and-test-code)
   - [Interactive Development Environment](#interactive-development-environment)
   - [Expose Services with Preview URLs](#expose-services-with-preview-urls)
+  - [Data Analysis with Code Interpreter](#data-analysis-with-code-interpreter)
 - [🏗️ Architecture](#architecture)
 - [🛠️ Advanced Usage](#advanced-usage)
   - [AsyncIterable Streaming Support](#asynciterable-streaming-support)
@@ -50,6 +55,9 @@ The Cloudflare Sandbox SDK enables you to run isolated code environments directl
 - **🔄 Git Integration**: Clone repositories directly into sandboxes
 - **🚀 Streaming Support**: Real-time output streaming for long-running commands
 - **🎮 Session Management**: Maintain state across multiple operations
+- **🧪 Code Interpreter**: Execute Python and JavaScript with rich outputs (charts, tables, formatted data)
+- **📊 Multi-Language Support**: Persistent execution contexts for Python and JavaScript/TypeScript
+- **🎨 Rich MIME Types**: Automatic processing of images, HTML, charts, and structured data
 
 <h2 id="quick-start">🚀 Quick Start</h2>
 
@@ -64,7 +72,7 @@ npm install @cloudflare/sandbox
 1. **Create a Dockerfile** (temporary requirement, will be removed in future releases):
 
 ```dockerfile
-FROM docker.io/cloudflare/sandbox:0.1.3
+FROM docker.io/cloudflare/sandbox:0.3.3
 
 # Expose the ports you want to expose
 EXPOSE 3000
@@ -81,7 +89,7 @@ EXPOSE 3000
     {
       "class_name": "Sandbox",
       "image": "./Dockerfile",
-      "max_instances": 1
+      "max_instances": 20
     }
   ],
   "durable_objects": {
@@ -176,7 +184,7 @@ for await (const log of parseSSEStream<LogEvent>(logStream)) {
 Write content to a file.
 
 ```typescript
-await sandbox.writeFile("/app.js", "console.log('Hello!');");
+await sandbox.writeFile("/workspace/app.js", "console.log('Hello!');");
 ```
 
 #### `readFile(path, options?)`
@@ -246,6 +254,131 @@ console.log(result.stdout); // "production"
 - `unexposePort(port)` - Remove port exposure
 - `getExposedPorts()` - List all exposed ports with their URLs
 
+#### Session Methods
+
+- `createSession(options)` - Create an isolated execution session
+  - `name`: Session identifier
+  - `env`: Environment variables for this session
+  - `cwd`: Working directory
+  - `isolation`: Enable PID namespace isolation (requires CAP_SYS_ADMIN)
+
+<h2 id="code-interpreter">🧪 Code Interpreter</h2>
+
+The Sandbox SDK includes powerful code interpreter capabilities, allowing you to execute Python and JavaScript code with rich outputs including charts, tables, and formatted data.
+
+### Code Execution
+
+#### `createCodeContext(options?)`
+
+Creates a new code execution context with persistent state.
+
+```typescript
+// Create a Python context
+const pythonCtx = await sandbox.createCodeContext({ language: 'python' });
+
+// Create a JavaScript context
+const jsCtx = await sandbox.createCodeContext({ language: 'javascript' });
+```
+
+**Options:**
+- `language`: Programming language (`'python'` | `'javascript'` | `'typescript'`)
+- `cwd`: Working directory (default: `/workspace`)
+- `envVars`: Environment variables for the context
+
+#### `runCode(code, options?)`
+
+Executes code with optional streaming callbacks.
+
+```typescript
+// Simple execution
+const execution = await sandbox.runCode('print("Hello World")', { 
+  context: pythonCtx 
+});
+
+// With streaming callbacks
+await sandbox.runCode(`
+for i in range(5):
+    print(f"Step {i}")
+    time.sleep(1)
+`, { 
+  context: pythonCtx,
+  onStdout: (output) => console.log('Real-time:', output.text),
+  onResult: (result) => console.log('Result:', result)
+});
+```
+
+**Options:**
+- `context`: Context to run the code in
+- `language`: Language if no context provided
+- `onStdout`: Callback for stdout output
+- `onStderr`: Callback for stderr output
+- `onResult`: Callback for execution results
+- `onError`: Callback for errors
+
+#### `runCodeStream(code, options?)`
+
+Returns a streaming response for real-time processing.
+
+```typescript
+const stream = await sandbox.runCodeStream('import time; [print(i) for i in range(10)]');
+// Process the stream as needed
+```
+
+### Rich Outputs
+
+The code interpreter automatically detects and processes various output types:
+
+```typescript
+// Data visualization
+const execution = await sandbox.runCode(`
+import matplotlib.pyplot as plt
+import numpy as np
+
+x = np.linspace(0, 10, 100)
+y = np.sin(x)
+plt.plot(x, y)
+plt.title('Sine Wave')
+plt.show()
+`, { 
+  context: pythonCtx,
+  onResult: (result) => {
+    if (result.png) {
+      // Base64 encoded PNG image
+      console.log('Chart generated!');
+    }
+  }
+});
+
+// HTML tables with pandas
+const tableExecution = await sandbox.runCode(`
+import pandas as pd
+df = pd.DataFrame({
+    'name': ['Alice', 'Bob', 'Charlie'],
+    'score': [92, 88, 95]
+})
+df
+`, { context: pythonCtx });
+
+// Access HTML table in execution.results[0].html
+```
+
+### Output Formats
+
+Results can include multiple formats:
+- `text`: Plain text representation
+- `html`: HTML (often pandas DataFrames)
+- `png`/`jpeg`: Base64 encoded images
+- `svg`: Vector graphics
+- `json`: Structured data
+- `chart`: Parsed chart information
+
+Check available formats with `result.formats()`.
+
+#### Additional Code Interpreter Methods
+
+- `listCodeContexts()` - List all active code contexts
+- `deleteCodeContext(contextId)` - Delete a specific context
+
 <h2 id="port-forwarding">🌐 Port Forwarding</h2>
 
 The SDK automatically handles preview URL routing for exposed ports. Just add one line to your worker:
@@ -314,7 +447,7 @@ const sandbox = getSandbox(env.Sandbox, "node-app");
 
 // Write a simple Express server
 await sandbox.writeFile(
-  "/app.js",
+  "/workspace/app.js",
   `
   const express = require('express');
   const app = express();
@@ -404,14 +537,100 @@ console.log(`Service available at: ${preview.url}`);
 // See the example in examples/basic/src/index.ts for the routing implementation.
 ```
 
+### Data Analysis with Code Interpreter
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, "analysis");
+
+// Create a Python context for data analysis
+const pythonCtx = await sandbox.createCodeContext({ language: 'python' });
+
+// Load and analyze data
+const analysis = await sandbox.runCode(`
+import pandas as pd
+import matplotlib.pyplot as plt
+
+# Create sample data
+data = {
+    'Month': ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
+    'Sales': [10000, 12000, 15000, 14000, 18000],
+    'Profit': [2000, 2500, 3200, 2800, 4000]
+}
+df = pd.DataFrame(data)
+
+# Display summary statistics
+print("Sales Summary:")
+print(df.describe())
+
+# Create visualization
+plt.figure(figsize=(10, 6))
+plt.subplot(1, 2, 1)
+plt.bar(df['Month'], df['Sales'])
+plt.title('Monthly Sales')
+plt.xlabel('Month')
+plt.ylabel('Sales ($)')
+
+plt.subplot(1, 2, 2)
+plt.plot(df['Month'], df['Profit'], marker='o', color='green')
+plt.title('Monthly Profit')
+plt.xlabel('Month')
+plt.ylabel('Profit ($)')
+
+plt.tight_layout()
+plt.show()
+
+# Return the data as JSON
+df.to_dict('records')
+`, { 
+  context: pythonCtx,
+  onResult: (result) => {
+    if (result.png) {
+      // Handle the chart image
+      console.log('Chart generated:', result.png.substring(0, 50) + '...');
+    }
+    if (result.json) {
+      // Handle the structured data
+      console.log('Data:', result.json);
+    }
+  }
+});
+
+// Multi-language workflow: Process in Python, analyze in JavaScript
+await sandbox.runCode(`
+# Save processed data
+df.to_json('/tmp/sales_data.json', orient='records')
+`, { context: pythonCtx });
+
+const jsCtx = await sandbox.createCodeContext({ language: 'javascript' });
+const jsAnalysis = await sandbox.runCode(`
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('/tmp/sales_data.json', 'utf8'));
+
+// Calculate growth rate
+const growth = data.map((curr, idx) => {
+  if (idx === 0) return { ...curr, growth: 0 };
+  const prev = data[idx - 1];
+  return {
+    ...curr,
+    growth: ((curr.Sales - prev.Sales) / prev.Sales * 100).toFixed(2) + '%'
+  };
+});
+
+console.log('Growth Analysis:', growth);
+growth;
+`, { context: jsCtx });
+```
+
 <h2 id="architecture">🏗️ Architecture</h2>
 
 The SDK leverages Cloudflare's infrastructure:
 
 - **Durable Objects**: Manages sandbox lifecycle and state
-- **Containers**: Provides isolated execution environments
+- **Containers**: Provides isolated execution environments with Jupyter kernels
 - **Workers**: Handles HTTP routing and API interface
 - **Edge Network**: Enables global distribution and low latency
+- **Jupyter Integration**: Python (IPython) and JavaScript (TSLab) kernels for code execution
+- **MIME Processing**: Automatic detection and handling of rich output formats
 
 <h2 id="advanced-usage">🛠️ Advanced Usage</h2>
 
@@ -492,17 +711,71 @@ for await (const log of parseSSEStream<LogEvent>(logStream)) {
 
 ### Session Management
 
-Maintain context across commands:
+The SDK provides two approaches for managing execution context:
+
+#### Implicit Sessions (Recommended)
+
+Each sandbox maintains its own persistent session automatically:
 
 ```typescript
-const sessionId = crypto.randomUUID();
+const sandbox = getSandbox(env.Sandbox, "my-app");
 
-// Commands in the same session share working directory
-await sandbox.exec("cd /app", { sessionId });
-await sandbox.exec("npm install", { sessionId });
-const app = await sandbox.startProcess("npm start", { sessionId });
+// These commands share state (pwd, env vars, etc.)
+await sandbox.exec("cd /app");
+await sandbox.exec("pwd");  // Output: /app
+await sandbox.exec("export MY_VAR=hello");
+await sandbox.exec("echo $MY_VAR");  // Output: hello
 ```
 
+#### Explicit Sessions for Advanced Use Cases
+
+Create isolated execution contexts within the same sandbox:
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, "multi-env");
+
+// Create independent sessions with different environments
+const buildSession = await sandbox.createSession({
+  name: "build",
+  env: { NODE_ENV: "production" },
+  cwd: "/build"
+});
+
+const testSession = await sandbox.createSession({
+  name: "test",
+  env: { NODE_ENV: "test" },
+  cwd: "/test"
+});
+
+// Run commands in parallel with different contexts
+await Promise.all([
+  buildSession.exec("npm run build"),
+  testSession.exec("npm test")
+]);
+```
+
+#### Security with AI Agents
+
+When using AI coding agents, separate development from execution:
+
+```typescript
+// Phase 1: AI agent writes code (with API keys)
+const devSession = await sandbox.createSession({
+  name: "ai-development",
+  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }
+});
+await devSession.exec('opencode "build a web server"');
+
+// Phase 2: Run the generated code (without API keys)
+const appSession = await sandbox.createSession({
+  name: "app-runtime",
+  env: { PORT: "3000" }  // Only app-specific vars
+});
+await appSession.exec("node server.js");
+```
+
+> **Best Practice**: Keep AI agent credentials separate from your application runtime to prevent accidental exposure of API keys.
+
 <h2 id="debugging">🔍 Debugging</h2>
 
 Enable verbose logging:
@@ -521,6 +794,9 @@ sandbox.client.onCommandComplete = (success, code) =>
 - Maximum container runtime is limited by Durable Object constraints
 - WebSocket support for preview URLs coming soon
 - Some system calls may be restricted in the container environment
+- Code interpreter has no internet access (sandbox restriction)
+- Some Python/JavaScript packages may not be pre-installed
+- Resource limits apply to code execution (CPU, memory)
 
 <h2 id="contributing">🤝 Contributing</h2>
 
@@ -534,11 +810,21 @@ cd sandbox-sdk
 # Install dependencies
 npm install
 
+# Install Bun (if not already installed)
+# Visit https://bun.sh for installation instructions
+curl -fsSL https://bun.sh/install | bash
+
+# Install container dependencies (required for TypeScript checking)
+cd packages/sandbox/container_src && bun install && cd -
+
 # Run tests
 npm test
 
 # Build the project
 npm run build
+
+# Run type checking and linting
+npm run check
 ```
 
 <h2 id="license">📄 License</h2>