@mastra/docker 0.0.0-a2a-vnext-20260424123427

package/dist/provider.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Docker Sandbox Provider Descriptor
+ *
+ * Enables registration with MastraEditor for UI-driven sandbox configuration.
+ */
+import type { SandboxProvider } from '@mastra/core/editor';
+/**
+ * Serializable config for the Docker sandbox provider.
+ * This is the subset of DockerSandboxOptions that can be stored in a config file
+ * and rendered in a UI form.
+ */
+export interface DockerProviderConfig {
+    /** Docker image to use */
+    image?: string;
+    /** Default command timeout in milliseconds */
+    timeout?: number;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Host-to-container bind mounts */
+    volumes?: Record<string, string>;
+    /** Docker network to join */
+    network?: string;
+    /** Working directory inside the container */
+    workingDir?: string;
+    /** Run in privileged mode */
+    privileged?: boolean;
+}
+export declare const dockerSandboxProvider: SandboxProvider<DockerProviderConfig>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAI3D;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,eAAO,MAAM,qBAAqB,EAAE,eAAe,CAAC,oBAAoB,CA4CvE,CAAC"}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Docker Sandbox Provider
+ *
+ * A Docker-based sandbox implementation that uses long-lived containers
+ * with `docker exec` for command execution. Targets local development,
+ * CI/CD, air-gapped deployments, and cost-sensitive scenarios where
+ * cloud sandboxes are overkill.
+ *
+ * @see https://docs.docker.com/engine/api/
+ */
+import type { RequestContext } from '@mastra/core/di';
+import type { SandboxInfo, ProviderStatus, MastraSandboxOptions } from '@mastra/core/workspace';
+import { MastraSandbox } from '@mastra/core/workspace';
+import Docker from 'dockerode';
+import type { Container } from 'dockerode';
+import { DockerProcessManager } from './process-manager.js';
+/**
+ * Inlined from `@mastra/core/workspace` to avoid requiring a newer core peer dep.
+ * Canonical type: packages/core/src/workspace/sandbox/mastra-sandbox.ts
+ * TODO: Remove once minimum peer dep includes InstructionsOption export.
+ */
+type InstructionsOption = string | ((opts: {
+    defaultInstructions: string;
+    requestContext?: RequestContext;
+}) => string);
+export interface DockerSandboxOptions extends Omit<MastraSandboxOptions, 'processes'> {
+    /** Unique identifier for this sandbox instance. Used for container naming and reconnection. */
+    id?: string;
+    /** Docker image to use.
+     * @default 'node:22-slim'
+     */
+    image?: string;
+    /** Container entrypoint command. Must keep the container alive.
+     * @default ['sleep', 'infinity']
+     */
+    command?: string[];
+    /** Environment variables to set in the container */
+    env?: Record<string, string>;
+    /** Host-to-container bind mounts (e.g., `{ '/host/path': '/container/path' }`) */
+    volumes?: Record<string, string>;
+    /** Docker network to join */
+    network?: string;
+    /** Run in privileged mode
+     * @default false
+     */
+    privileged?: boolean;
+    /** Default command timeout in milliseconds
+     * @default 300_000 // 5 minutes
+     */
+    timeout?: number;
+    /** Working directory inside the container
+     * @default '/workspace'
+     */
+    workingDir?: string;
+    /** Container labels for filtering and identification */
+    labels?: Record<string, string>;
+    /** Pass-through dockerode connection options (socket path, host, TLS certs) */
+    dockerOptions?: Docker.DockerOptions;
+    /**
+     * Custom instructions that override the default instructions
+     * returned by `getInstructions()`.
+     *
+     * - `string` — Fully replaces the default instructions.
+     *   Pass an empty string to suppress instructions entirely.
+     * - `(opts) => string` — Receives the default instructions and
+     *   optional request context so you can extend or customise per-request.
+     */
+    instructions?: InstructionsOption;
+}
+/**
+ * Docker sandbox implementation using long-lived containers.
+ *
+ * Features:
+ * - Long-lived container with `docker exec` for commands
+ * - Bind mount support via Docker volumes
+ * - Reconnection to existing containers by ID/name
+ * - Container label tracking for discovery
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Workspace } from '@mastra/core/workspace';
+ * import { DockerSandbox } from '@mastra/docker';
+ *
+ * const sandbox = new DockerSandbox({
+ *   image: 'node:22-slim',
+ *   timeout: 60000,
+ * });
+ *
+ * const workspace = new Workspace({ sandbox });
+ * const result = await workspace.executeCode('console.log("Hello!")');
+ * ```
+ *
+ * @example With bind mounts
+ * ```typescript
+ * const sandbox = new DockerSandbox({
+ *   image: 'node:22-slim',
+ *   volumes: { '/my/project': '/workspace/project' },
+ * });
+ * ```
+ */
+export declare class DockerSandbox extends MastraSandbox {
+    readonly id: string;
+    readonly name = "DockerSandbox";
+    readonly provider = "docker";
+    status: ProviderStatus;
+    readonly processes: DockerProcessManager;
+    /** Underlying Docker client */
+    private readonly _docker;
+    /** Container reference (set after start) */
+    private _container;
+    /** Configuration */
+    private readonly _image;
+    private readonly _command;
+    private readonly _env;
+    private readonly _volumes;
+    private readonly _network?;
+    private readonly _privileged;
+    private readonly _workingDir;
+    private readonly _labels;
+    private readonly _instructionsOverride?;
+    constructor(options?: DockerSandboxOptions);
+    /**
+     * Get the underlying Docker container for direct access.
+     * @throws {SandboxNotReadyError} If the sandbox has not been started.
+     */
+    get container(): Container;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+    getInstructions(opts?: {
+        requestContext?: RequestContext;
+    }): string;
+    getInfo(): Promise<SandboxInfo>;
+    private _generateId;
+    /**
+     * Resolve the container reference, looking up by label if `_container` is unset.
+     * This ensures `stop()` and `destroy()` work even when the instance was created
+     * with an existing container's ID but `start()` was never called.
+     */
+    private _resolveContainer;
+    /**
+     * Find an existing container matching this sandbox's ID via labels.
+     */
+    private _findExistingContainer;
+    /**
+     * Ensure the Docker image is available locally. Pulls if needed.
+     */
+    private _ensureImage;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/process-manager.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Docker Process Manager
+ *
+ * Implements SandboxProcessManager for Docker containers.
+ * Uses `container.exec()` to run commands inside a long-lived container.
+ * Each spawned process gets a dedicated exec instance with separate
+ * stdout/stderr streams.
+ */
+import { ProcessHandle, SandboxProcessManager } from '@mastra/core/workspace';
+import type { ProcessInfo, SpawnProcessOptions } from '@mastra/core/workspace';
+import type { Container } from 'dockerode';
+/**
+ * Docker implementation of SandboxProcessManager.
+ * Uses `container.exec()` with stream-based I/O.
+ */
+export declare class DockerProcessManager extends SandboxProcessManager {
+    private _container;
+    private readonly _defaultTimeout;
+    constructor(options: {
+        env: Record<string, string>;
+        defaultTimeout?: number;
+    });
+    /** @internal Called by DockerSandbox after container is ready */
+    setContainer(container: Container): void;
+    /** Get the container, throwing if not set */
+    private get container();
+    spawn(command: string, options?: SpawnProcessOptions): Promise<ProcessHandle>;
+    /** Clear all tracked process handles and release the container reference (e.g., after container stop/destroy) */
+    reset(): void;
+    list(): Promise<ProcessInfo[]>;
+}
+//# sourceMappingURL=process-manager.d.ts.map

package/dist/sandbox/process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../src/sandbox/process-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EAAiB,WAAW,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC9F,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AA6JlE;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,qBAAqB;IAC7D,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE;IAK7E,iEAAiE;IACjE,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC,6CAA6C;IAC7C,OAAO,KAAK,SAAS,GAKpB;IAEK,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC;IAgJvF,iHAAiH;IACjH,KAAK,IAAI,IAAI;IAKP,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAcrC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@mastra/docker",
+  "version": "0.0.0-a2a-vnext-20260424123427",
+  "description": "Docker container sandbox provider for Mastra workspaces",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "dockerode": "^4.0.9"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^4.0.1",
+    "@types/node": "22.19.15",
+    "@vitest/coverage-v8": "4.1.5",
+    "@vitest/ui": "4.1.5",
+    "eslint": "^10.2.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.5",
+    "@internal/lint": "0.0.0-a2a-vnext-20260424123427",
+    "@internal/types-builder": "0.0.0-a2a-vnext-20260424123427",
+    "@internal/workspace-test-utils": "0.0.30",
+    "@mastra/core": "0.0.0-a2a-vnext-20260424123427"
+  },
+  "peerDependencies": {
+    "@mastra/core": "0.0.0-a2a-vnext-20260424123427"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "homepage": "https://mastra.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mastra-ai/mastra.git",
+    "directory": "workspaces/docker"
+  },
+  "bugs": {
+    "url": "https://github.com/mastra-ai/mastra/issues"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsup --silent --config tsup.config.ts",
+    "build:lib": "pnpm build",
+    "build:watch": "pnpm build --watch",
+    "test:unit": "vitest run --exclude '**/*.integration.test.ts'",
+    "test:watch": "vitest watch",
+    "test": "vitest run ./src/**/*.integration.test.ts",
+    "test:cloud": "pnpm test",
+    "lint": "eslint ."
+  }
+}