@computesdk/docker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 computesdk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,349 @@
+# @computesdk/docker
+
+A Docker-based provider for [ComputeSDK](https://github.com/computesdk/computesdk) that launches lightweight, configurable containers (Python or Node.js), runs code and shell commands, and offers simple filesystem helpers — all behind a clean, provider-agnostic interface.
+
+---
+
+## Installation
+
+```bash
+# like the other computesdk providers — single package
+pnpm add @computesdk/docker
+# or
+npm i @computesdk/docker
+# or
+yarn add @computesdk/docker
+```
+
+> You **do** need a working Docker Engine/Daemon on the host where this runs.
+
+---
+
+## Setup
+
+Nothing special beyond Docker. The provider talks to Docker through `dockerode`, which autodetects your connection from env or the default socket.
+
+Common environment variables (used by Docker/dockerode):
+
+* `DOCKER_HOST` — e.g. `unix:///var/run/docker.sock` (Linux/macOS) or `tcp://127.0.0.1:2375`
+* `DOCKER_TLS_VERIFY`, `DOCKER_CERT_PATH` — for TLS-secured TCP
+* `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` — for pulls behind a proxy
+
+> On Linux, ensure your user can access Docker: `sudo usermod -aG docker $USER` then re-login, or run with `sudo`.
+
+---
+
+## Usage
+
+You can use the provider directly or via the ComputeSDK singleton.
+
+### With ComputeSDK
+
+```ts
+import { createCompute } from 'computesdk';
+import { docker } from '@computesdk/docker';
+
+const provider = docker({
+  runtime: 'python', // or 'node'
+  image: { name: 'python:3.11-slim', pullPolicy: 'ifNotPresent' },
+});
+
+const compute = createCompute({ defaultProvider: provider });
+
+// Create a sandbox and run Python
+const py = await compute.sandbox.create();
+const out = await py.runCode(`print("Hello from Python")`, 'python');
+console.log(out.stdout.trim()); // Hello from Python
+
+await py.destroy();
+```
+
+### Direct Usage
+
+```ts
+import { docker } from '@computesdk/docker';
+
+const provider = docker({
+  runtime: 'node',
+  image: { name: 'node:20-alpine' },
+  container: {
+    workdir: '/workspace',
+    env: { FOO: 'bar' },
+  },
+});
+
+const sb = await provider.sandbox.create({ runtime: 'node' });
+
+const res = await sb.runCode(`console.log("Hello, World!")`, 'node');
+console.log(res.stdout.trim()); // Hello, World!
+
+const ls = await sb.runCommand('sh', ['-lc', 'echo Hello from command']);
+console.log(ls.stdout.trim()); // Hello from command
+
+await sb.destroy();
+```
+
+---
+
+## Configuration
+
+Type: `DockerConfig`
+
+```ts
+{
+  // dockerode connection; if omitted, dockerode uses DOCKER_HOST or /var/run/docker.sock
+  connection?: import('dockerode').DockerOptions;
+
+  // default runtime; must be 'python' or 'node'
+  runtime?: 'python' | 'node';
+
+  // provider-side execution timeout (ms)
+  timeout?: number;
+
+  // image to use for containers
+  image: {
+    name: string;                   // e.g. 'python:3.11-slim' or 'node:20-alpine'
+    pullPolicy?: 'always' | 'ifNotPresent' | 'never';
+    auth?: { username?: string; password?: string; serveraddress?: string; identitytoken?: string; registrytoken?: string; };
+  };
+
+  // container defaults
+  container?: {
+    user?: string;
+    workdir?: string;
+    env?: Record<string, string>;
+    binds?: string[];               // ['/host:/container:ro']
+    ports?: Record<`${number}/${'tcp'|'udp'}`, Array<{ hostPort?: number; hostIP?: string }>>;
+    networkMode?: string;           // 'bridge', 'host', custom
+    privileged?: boolean;
+    capabilities?: { add?: string[]; drop?: string[] };
+    gpus?: 'all' | number | string; // requires NVIDIA runtime/drivers
+    resources?: { memory?: number; nanoCPUs?: number; cpuShares?: number; /* … */ };
+    logDriver?: string;
+    logOpts?: Record<string, string>;
+    autoRemove?: boolean;           // default true
+    tty?: boolean;
+    openStdin?: boolean;
+  };
+
+  // raw passthrough if you need full control
+  createOptions?: import('dockerode').ContainerCreateOptions;
+  startOptions?: import('dockerode').ContainerStartOptions;
+
+  cleanup?: 'always' | 'onSuccess' | 'never';
+  streamLogs?: boolean;
+}
+```
+
+**Defaults (excerpt):**
+
+```ts
+{
+  runtime: 'python',
+  image: { name: 'python:3.11-slim', pullPolicy: 'ifNotPresent' },
+  container: {
+    workdir: '/workspace',
+    env: {},
+    autoRemove: true,
+    tty: false,
+    openStdin: false,
+    resources: { memory: 512 * 1024 * 1024 },
+  },
+}
+```
+
+### Environment Variables
+
+* Docker connection variables from **Setup**
+* Your workload envs via `container.env` (injected into the container)
+
+---
+
+## Features
+
+* **Python** and **Node.js** runtimes
+* **Code execution** with syntax-error surfacing
+* **Shell commands** (foreground & background with PID)
+* **Filesystem helpers**: `readFile`, `writeFile`, `mkdir`, `readdir`, `exists`, `remove`
+* **Port URL resolution**: `getUrl({ port })` → host URL if published
+* **Typed access**: `getInstance()` returns the dockerode `Container` and client
+* **Image pull policy**: `always | ifNotPresent | never` (+ registry auth)
+
+---
+
+## API Reference
+
+### Code Execution
+
+```ts
+sandbox.runCode(code: string, runtime?: 'python' | 'node'): Promise<ExecutionResult>
+```
+
+* If `runtime` omitted, the sandbox’s runtime (set at creation) is used.
+* Returns `{ stdout, stderr, exitCode, executionTime, sandboxId, provider }`
+* Syntax errors are **thrown** as `Error("Syntax error: …")`.
+
+### Command Execution
+
+```ts
+sandbox.runCommand(command: string, args?: string[], options?: { background?: boolean }): Promise<ExecutionResult>
+```
+
+* Runs via `/bin/sh -c "…"` with stdout/stderr capture.
+* Background returns `{ isBackground: true, pid?: number }`.
+
+### Filesystem Operations
+
+```ts
+sandbox.filesystem.readFile(path)
+sandbox.filesystem.writeFile(path, content)
+sandbox.filesystem.mkdir(path)
+sandbox.filesystem.readdir(path)
+sandbox.filesystem.exists(path)
+sandbox.filesystem.remove(path)
+```
+
+> Implemented via shell + base64 for portability.
+
+### Terminal Operations
+
+Interactive terminals aren’t exposed. Use `runCommand('sh', ['-lc', '…'])` for non-interactive sessions.
+
+### Sandbox Management
+
+```ts
+const sb = await provider.sandbox.create({ runtime?: 'python' | 'node' });
+await provider.sandbox.destroy(sb.sandboxId);
+
+await sb.getInfo(); // { id, provider, runtime, status, createdAt, timeout, metadata }
+await sb.getUrl({ port, protocol?: 'http' | 'https' });
+sb.getInstance(); // { docker: Docker, container: Container, ... }
+```
+
+---
+
+## Runtime Detection
+
+There’s **no auto-detection**. Resolution is:
+
+1. `runCode(_, runtime)` argument, else
+2. runtime label set at `sandbox.create()` (from `options.runtime` or provider `config.runtime`)
+
+If neither yields `'python' | 'node'`, `runCode` throws.
+
+---
+
+## Error Handling
+
+* **Syntax errors** → **thrown** (`Error("Syntax error: …")`)
+* **Runtime/command errors** → returned as non-zero `exitCode` with `stderr`
+* **Docker errors** (pull/start/exec) → **thrown**
+
+```ts
+const res = await sb.runCommand('sh', ['-lc', 'bad-command']);
+if (res.exitCode !== 0) {
+  console.error('stderr:', res.stderr);
+}
+```
+
+---
+
+## Web Framework Integration
+
+```ts
+import { handleComputeRequest } from 'computesdk';
+import { docker } from '@computesdk/docker';
+
+const provider = docker({
+  runtime: 'node',
+  image: { name: 'node:20-alpine' },
+});
+
+export async function POST(req: Request) {
+  const body = await req.json(); // ComputeRequest
+  return handleComputeRequest(body, provider);
+}
+```
+
+---
+
+## Examples
+
+### Data Science Workflow (Python)
+
+```ts
+const py = await provider.sandbox.create({ runtime: 'python' });
+await py.runCommand('sh', ['-lc', 'python3 -m pip install --no-cache-dir pandas']);
+await py.filesystem.writeFile('/workspace/app.py', `
+import pandas as pd
+print("rows:", len(pd.DataFrame({"x":[1,2,3]})))
+`);
+const run = await py.runCommand('sh', ['-lc', 'python3 /workspace/app.py']);
+console.log(run.stdout.trim()); // rows: 3
+await py.destroy();
+```
+
+### Interactive-like Loop
+
+```ts
+const sb = await provider.sandbox.create({ runtime: 'node' });
+await sb.runCommand('sh', ['-lc', 'echo boot > /tmp/state']);
+await sb.runCommand('sh', ['-lc', 'cat /tmp/state']); // 'boot'
+await sb.destroy();
+```
+
+### Machine Learning Pipeline (Python + Ports)
+
+```ts
+const sb = await provider.sandbox.create({ runtime: 'python' });
+const bg = await sb.runCommand('sh', ['-lc', 'python3 -m http.server 8080'], { background: true });
+const url = await sb.getUrl({ port: 8080 });
+console.log('Serving at', url);
+await sb.destroy();
+```
+
+> To make ports reachable from the host, publish them up front:
+>
+> ```ts
+> const provider = docker({
+>   runtime: 'python',
+>   image: { name: 'python:3.11-slim' },
+>   container: {
+>     ports: { '8080/tcp': [{ hostPort: 8080, hostIP: '127.0.0.1' }] },
+>   },
+> });
+> ```
+
+---
+
+## Best Practices
+
+* Pre-pull images in CI: `docker pull python:3.11-slim node:20-alpine`
+* Pin image versions; avoid `latest`
+* Set `container.resources` to bound CPU/RAM
+* Use `/workspace` and keep temp files in `/tmp`
+* Publish ports you intend to access via `getUrl()`
+* Prefer non-root `user` and drop unnecessary capabilities
+* For GPU work: `gpus: 'all'` and ensure NVIDIA runtime/drivers
+
+---
+
+## Limitations
+
+* Requires a local or reachable Docker daemon
+* No WebSocket terminal (non-interactive only)
+* Snapshots/templates not implemented in this provider
+* `getUrl()` returns a host URL only for published ports or reachable container IPs
+
+---
+
+## Support
+
+* Issues/PRs: [https://github.com/computesdk/computesdk](https://github.com/computesdk/computesdk)
+* Open issues with title prefix **\[docker provider]**
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,120 @@
+import * as computesdk from 'computesdk';
+import { Runtime, CreateSandboxOptions, ExecutionResult, RunCommandOptions, SandboxInfo, FileEntry } from 'computesdk';
+import Docker, { DockerOptions, ContainerCreateOptions, ContainerStartOptions, Container } from 'dockerode';
+
+/** When the provider should clean up containers it created */
+type CleanupPolicy = 'always' | 'onSuccess' | 'never';
+/** Image pull strategy */
+type PullPolicy = 'always' | 'ifNotPresent' | 'never';
+/** Connection to the Docker daemon (exactly what dockerode accepts) */
+type DockerConnection = DockerOptions;
+/** Auth when pulling private images (Engine API AuthConfig shape) */
+interface RegistryAuth {
+    username?: string;
+    password?: string;
+    serveraddress?: string;
+    identitytoken?: string;
+    registrytoken?: string;
+}
+/** Default image & pull policy for sandboxes */
+interface DockerImage {
+    name: string;
+    pullPolicy?: PullPolicy;
+    auth?: RegistryAuth;
+}
+/** Convenience shape for port bindings */
+type PortBindings = Record<`${number}/${'tcp' | 'udp'}`, Array<{
+    hostPort?: number;
+    hostIP?: string;
+}>>;
+/** Subset of HostConfig resources & knobs that are commonly used */
+interface ResourceLimits {
+    cpuShares?: number;
+    cpuQuota?: number;
+    cpuPeriod?: number;
+    nanoCPUs?: number;
+    memory?: number;
+    memorySwap?: number;
+    pidsLimit?: number;
+}
+/** Declarative container defaults that we’ll translate into dockerode create options */
+interface ContainerDefaults {
+    user?: string;
+    workdir?: string;
+    env?: Record<string, string>;
+    binds?: string[];
+    ports?: PortBindings;
+    networkMode?: string;
+    privileged?: boolean;
+    capabilities?: {
+        add?: string[];
+        drop?: string[];
+    };
+    gpus?: 'all' | number | string;
+    resources?: ResourceLimits;
+    logDriver?: string;
+    logOpts?: Record<string, string>;
+    autoRemove?: boolean;
+    tty?: boolean;
+    openStdin?: boolean;
+}
+/** Provider-level configuration for Docker */
+interface DockerConfig {
+    connection?: DockerConnection;
+    runtime?: Runtime;
+    timeout?: number;
+    image: DockerImage;
+    container?: ContainerDefaults;
+    createOptions?: ContainerCreateOptions;
+    startOptions?: ContainerStartOptions;
+    cleanup?: CleanupPolicy;
+    streamLogs?: boolean;
+}
+/** What we keep for each running sandbox */
+interface DockerSandboxHandle {
+    docker: Docker;
+    container: Container;
+    containerId: string;
+    image: string;
+    createdAt: Date;
+}
+/** URL options for port-forwarded services */
+interface DockerUrlOptions {
+    port: number;
+    protocol?: 'http' | 'https';
+    host?: string;
+}
+/** Optional FS helpers you might expose */
+interface DockerSandboxFileSystem {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    readdir(path: string): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    remove(path: string): Promise<void>;
+}
+/** Strongly-typed sandbox API shape */
+interface DockerSandboxAPI {
+    sandboxId: string;
+    provider: 'docker';
+    runCode(code: string, runtime?: Runtime): Promise<ExecutionResult>;
+    runCommand(command: string, args?: string[], options?: RunCommandOptions): Promise<ExecutionResult>;
+    getInfo(): Promise<SandboxInfo>;
+    getUrl(options: DockerUrlOptions): Promise<string>;
+    getProvider(): any;
+    getInstance(): DockerSandboxHandle;
+    kill(): Promise<void>;
+    destroy(): Promise<void>;
+    filesystem: DockerSandboxFileSystem;
+}
+/** Factory return shape mirroring your createE2BCompute helper */
+interface CreateDockerCompute {
+    sandbox: {
+        create(options?: CreateSandboxOptions): Promise<DockerSandboxAPI>;
+    };
+}
+
+declare const docker: (config: DockerConfig) => computesdk.Provider<DockerSandboxHandle, any, any>;
+declare function createDockerCompute(config: DockerConfig): CreateDockerCompute;
+
+export { createDockerCompute, docker };

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import * as computesdk from 'computesdk';
+import { Runtime, CreateSandboxOptions, ExecutionResult, RunCommandOptions, SandboxInfo, FileEntry } from 'computesdk';
+import Docker, { DockerOptions, ContainerCreateOptions, ContainerStartOptions, Container } from 'dockerode';
+
+/** When the provider should clean up containers it created */
+type CleanupPolicy = 'always' | 'onSuccess' | 'never';
+/** Image pull strategy */
+type PullPolicy = 'always' | 'ifNotPresent' | 'never';
+/** Connection to the Docker daemon (exactly what dockerode accepts) */
+type DockerConnection = DockerOptions;
+/** Auth when pulling private images (Engine API AuthConfig shape) */
+interface RegistryAuth {
+    username?: string;
+    password?: string;
+    serveraddress?: string;
+    identitytoken?: string;
+    registrytoken?: string;
+}
+/** Default image & pull policy for sandboxes */
+interface DockerImage {
+    name: string;
+    pullPolicy?: PullPolicy;
+    auth?: RegistryAuth;
+}
+/** Convenience shape for port bindings */
+type PortBindings = Record<`${number}/${'tcp' | 'udp'}`, Array<{
+    hostPort?: number;
+    hostIP?: string;
+}>>;
+/** Subset of HostConfig resources & knobs that are commonly used */
+interface ResourceLimits {
+    cpuShares?: number;
+    cpuQuota?: number;
+    cpuPeriod?: number;
+    nanoCPUs?: number;
+    memory?: number;
+    memorySwap?: number;
+    pidsLimit?: number;
+}
+/** Declarative container defaults that we’ll translate into dockerode create options */
+interface ContainerDefaults {
+    user?: string;
+    workdir?: string;
+    env?: Record<string, string>;
+    binds?: string[];
+    ports?: PortBindings;
+    networkMode?: string;
+    privileged?: boolean;
+    capabilities?: {
+        add?: string[];
+        drop?: string[];
+    };
+    gpus?: 'all' | number | string;
+    resources?: ResourceLimits;
+    logDriver?: string;
+    logOpts?: Record<string, string>;
+    autoRemove?: boolean;
+    tty?: boolean;
+    openStdin?: boolean;
+}
+/** Provider-level configuration for Docker */
+interface DockerConfig {
+    connection?: DockerConnection;
+    runtime?: Runtime;
+    timeout?: number;
+    image: DockerImage;
+    container?: ContainerDefaults;
+    createOptions?: ContainerCreateOptions;
+    startOptions?: ContainerStartOptions;
+    cleanup?: CleanupPolicy;
+    streamLogs?: boolean;
+}
+/** What we keep for each running sandbox */
+interface DockerSandboxHandle {
+    docker: Docker;
+    container: Container;
+    containerId: string;
+    image: string;
+    createdAt: Date;
+}
+/** URL options for port-forwarded services */
+interface DockerUrlOptions {
+    port: number;
+    protocol?: 'http' | 'https';
+    host?: string;
+}
+/** Optional FS helpers you might expose */
+interface DockerSandboxFileSystem {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    readdir(path: string): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    remove(path: string): Promise<void>;
+}
+/** Strongly-typed sandbox API shape */
+interface DockerSandboxAPI {
+    sandboxId: string;
+    provider: 'docker';
+    runCode(code: string, runtime?: Runtime): Promise<ExecutionResult>;
+    runCommand(command: string, args?: string[], options?: RunCommandOptions): Promise<ExecutionResult>;
+    getInfo(): Promise<SandboxInfo>;
+    getUrl(options: DockerUrlOptions): Promise<string>;
+    getProvider(): any;
+    getInstance(): DockerSandboxHandle;
+    kill(): Promise<void>;
+    destroy(): Promise<void>;
+    filesystem: DockerSandboxFileSystem;
+}
+/** Factory return shape mirroring your createE2BCompute helper */
+interface CreateDockerCompute {
+    sandbox: {
+        create(options?: CreateSandboxOptions): Promise<DockerSandboxAPI>;
+    };
+}
+
+declare const docker: (config: DockerConfig) => computesdk.Provider<DockerSandboxHandle, any, any>;
+declare function createDockerCompute(config: DockerConfig): CreateDockerCompute;
+
+export { createDockerCompute, docker };