@cloudflare/sandbox 0.2.4 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @cloudflare/sandbox
 
+## 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

package/Dockerfile

@@ -33,7 +33,6 @@ RUN apt-get update && apt-get install -y \
     python3-pip \
     python3.11-venv \
     # Other useful tools
-    sudo \
     ca-certificates \
     gnupg \
     lsb-release \
@@ -43,13 +42,8 @@ RUN apt-get update && apt-get install -y \
 # Set Python 3.11 as default python3
 RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
 
-# Install Node.js 20 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_20.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/*
 
@@ -73,7 +67,7 @@ RUN pip3 install --no-cache-dir \
     seaborn
 
 # Install JavaScript kernel (ijavascript) - using E2B's fork
-RUN npm install -g --unsafe-perm git+https://github.com/e2b-dev/ijavascript.git \
+RUN npm install -g git+https://github.com/e2b-dev/ijavascript.git \
     && ijsinstall --install=global
 
 # Set up container server directory
@@ -88,11 +82,15 @@ RUN python3 --version && \
     jupyter kernelspec list
 
 # Copy container source files to server directory
-COPY container_src/package.json ./
-RUN bun install
+COPY container_src/package.json container_src/bun.lock ./
+RUN bun install --frozen-lockfile
 
 COPY container_src/ ./
 
+# Compile TypeScript control process
+# Use npx -p typescript to ensure we get the right tsc command
+RUN npx -p typescript tsc control-process.ts --outDir . --module commonjs --target es2020 --esModuleInterop --skipLibCheck
+
 # Create clean workspace directory for users
 RUN mkdir -p /workspace
 

package/README.md

@@ -72,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.2.4
+FROM docker.io/cloudflare/sandbox:0.3.1
 
 # Expose the ports you want to expose
 EXPOSE 3000
@@ -254,6 +254,14 @@ 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.
@@ -703,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 /workspace", { 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: