@cloudflare/sandbox 0.0.0-4aceb32 → 0.0.0-4bedc3a

package/CHANGELOG.md

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

package/Dockerfile

@@ -33,22 +33,17 @@ RUN apt-get update && apt-get install -y \
     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 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/*
 
@@ -56,20 +51,23 @@ 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 Jupyter and kernels
+# Install minimal Jupyter components
 RUN pip3 install --no-cache-dir \
-    jupyter \
-    jupyterlab \
+    jupyter-server \
+    jupyter-client \
     ipykernel \
-    notebook \
+    orjson \
+    && python3 -m ipykernel install --user --name python3
+
+# Install scientific packages
+RUN pip3 install --no-cache-dir \
     matplotlib \
     numpy \
     pandas \
-    seaborn \
-    && python3 -m ipykernel install --user --name python3
+    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
@@ -84,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.1
+FROM docker.io/cloudflare/sandbox:0.2.4
 
 # 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: