@mastra/docker 0.0.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# @mastra/docker
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Added @mastra/docker, a Docker container sandbox provider for Mastra workspaces. Executes commands inside local Docker containers using long-lived containers with `docker exec`. Supports bind mounts, environment variables, container reconnection by label, custom images, and network configuration. Targets local development, CI/CD, air-gapped deployments, and cost-sensitive scenarios where cloud sandboxes are unnecessary. ([#14500](https://github.com/mastra-ai/mastra/pull/14500))
+
+  **Usage**
+
+  ```typescript
+  import { Agent } from '@mastra/core/agent';
+  import { Workspace } from '@mastra/core/workspace';
+  import { DockerSandbox } from '@mastra/docker';
+
+  const workspace = new Workspace({
+    sandbox: new DockerSandbox({
+      image: 'node:22-slim',
+      timeout: 60_000,
+    }),
+  });
+
+  const agent = new Agent({
+    name: 'dev-agent',
+    model: 'anthropic/claude-opus-4-6',
+    workspace,
+  });
+  ```
+
+### Patch Changes
+
+- Fixed process kill to target the entire process group (negative PID) with fallback, ensuring child processes spawned inside the container are properly cleaned up. Tracked process handles are now cleared after container stop or destroy to prevent stale references. ([#14500](https://github.com/mastra-ai/mastra/pull/14500))
+
+- Updated dependencies [[`0474c2b`](https://github.com/mastra-ai/mastra/commit/0474c2b2e7c7e1ad8691dca031284841391ff1ef), [`f607106`](https://github.com/mastra-ai/mastra/commit/f607106854c6416c4a07d4082604b9f66d047221), [`62919a6`](https://github.com/mastra-ai/mastra/commit/62919a6ee0fbf3779ad21a97b1ec6696515d5104), [`0fd90a2`](https://github.com/mastra-ai/mastra/commit/0fd90a215caf5fca8099c15a67ca03e4427747a3)]:
+  - @mastra/core@1.26.0-alpha.4

package/README.md

@@ -0,0 +1,80 @@
+# @mastra/docker
+
+Docker container sandbox provider for Mastra workspaces. 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 unnecessary.
+
+## Installation
+
+```bash
+npm install @mastra/docker
+```
+
+Requires [Docker Engine](https://docs.docker.com/engine/install/) running on the host machine.
+
+## Usage
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { Workspace } from '@mastra/core/workspace';
+import { DockerSandbox } from '@mastra/docker';
+
+const workspace = new Workspace({
+  sandbox: new DockerSandbox({
+    image: 'node:22-slim',
+    timeout: 60_000, // 60 second timeout (default: 5 minutes)
+  }),
+});
+
+const agent = new Agent({
+  name: 'my-agent',
+  model: 'anthropic/claude-opus-4-6',
+  workspace,
+});
+```
+
+### Bind Mounts
+
+Mount host directories into the container:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new DockerSandbox({
+    image: 'node:22-slim',
+    volumes: {
+      '/my/project': '/workspace/project',
+      '/shared/data': '/data',
+    },
+  }),
+});
+```
+
+### Reconnection
+
+Containers can be reconnected by providing a fixed `id`. On `start()`, an existing container with a matching label is reused instead of creating a new one:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new DockerSandbox({
+    id: 'persistent-sandbox',
+    image: 'node:22-slim',
+  }),
+});
+```
+
+### Docker Connection Options
+
+Connect to remote Docker hosts or use custom socket paths:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new DockerSandbox({
+    dockerOptions: {
+      host: '192.168.1.100',
+      port: 2376,
+    },
+  }),
+});
+```
+
+## Documentation
+
+For more information, see the [DockerSandbox reference](https://mastra.ai/docs/reference/workspace/docker-sandbox).

package/dist/index.cjs

@@ -0,0 +1,572 @@
+'use strict';
+
+var workspace = require('@mastra/core/workspace');
+var Docker = require('dockerode');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Docker__default = /*#__PURE__*/_interopDefault(Docker);
+
+// src/sandbox/index.ts
+var DockerProcessHandle = class extends workspace.ProcessHandle {
+  pid;
+  _exec;
+  _container;
+  _startTime;
+  _exitCode;
+  /** @internal Set by kill() and timeout to distinguish forced termination from natural exit */
+  _killed = false;
+  _waitPromise = null;
+  _stdinStream = null;
+  _execStream = null;
+  constructor(exec, container, startTime, stdinStream, options) {
+    super(options);
+    this.pid = exec.id;
+    this._exec = exec;
+    this._container = container;
+    this._startTime = startTime;
+    this._stdinStream = stdinStream;
+  }
+  get exitCode() {
+    return this._exitCode;
+  }
+  /** @internal Set exit code when stream closes */
+  _setExitCode(code) {
+    this._exitCode = code;
+  }
+  /** @internal Set the wait promise from spawn */
+  _setWaitPromise(p) {
+    this._waitPromise = p;
+  }
+  /** @internal Set the exec stream so kill() can destroy it */
+  _setExecStream(stream) {
+    this._execStream = stream;
+  }
+  async wait() {
+    if (this._waitPromise) {
+      return this._waitPromise;
+    }
+    const info = await this._inspectExec();
+    return {
+      success: (info.ExitCode ?? 1) === 0,
+      exitCode: info.ExitCode ?? 1,
+      stdout: this.stdout,
+      stderr: this.stderr,
+      executionTimeMs: Date.now() - this._startTime
+    };
+  }
+  async kill() {
+    if (this._exitCode !== void 0) return false;
+    try {
+      let info = await this._inspectExec();
+      if (!info.Running || !info.Pid) {
+        await new Promise((r) => setTimeout(r, 50));
+        info = await this._inspectExec();
+      }
+      if (!info.Running) {
+        this._killed = true;
+        this._destroyStream();
+        return false;
+      }
+      const pid = info.Pid;
+      if (!pid) {
+        this._killed = true;
+        this._destroyStream();
+        return false;
+      }
+      const killExec = await this._container.exec({
+        Cmd: ["sh", "-c", `kill -9 -${pid} 2>/dev/null || kill -9 ${pid}`],
+        AttachStdout: false,
+        AttachStderr: false
+      });
+      await killExec.start({});
+      this._killed = true;
+      this._destroyStream();
+      return true;
+    } catch (error) {
+      this._killed = true;
+      this._destroyStream();
+      const msg = error instanceof Error ? error.message.toLowerCase() : "";
+      if (!msg.includes("no such process") && !msg.includes("esrch")) {
+        console.warn(`[DockerProcessManager] kill(${this.pid}) failed unexpectedly:`, error);
+      }
+      return false;
+    }
+  }
+  async sendStdin(data) {
+    if (this._exitCode !== void 0) {
+      throw new Error(`Process ${this.pid} has already exited with code ${this._exitCode}`);
+    }
+    if (!this._stdinStream) {
+      throw new Error(`Process ${this.pid} was not started with stdin support`);
+    }
+    this._stdinStream.write(data);
+  }
+  /** @internal Force-close the exec stream to unblock wait(). */
+  _destroyStream() {
+    const stream = this._execStream;
+    if (stream && typeof stream.destroy === "function") {
+      stream.destroy();
+      this._execStream = null;
+    }
+  }
+  async _inspectExec() {
+    return this._exec.inspect();
+  }
+};
+var DockerProcessManager = class extends workspace.SandboxProcessManager {
+  _container = null;
+  _defaultTimeout;
+  constructor(options) {
+    super(options);
+    this._defaultTimeout = options.defaultTimeout ?? 0;
+  }
+  /** @internal Called by DockerSandbox after container is ready */
+  setContainer(container) {
+    this._container = container;
+  }
+  /** Get the container, throwing if not set */
+  get container() {
+    if (!this._container) {
+      throw new Error("Docker container not available. Has the sandbox been started?");
+    }
+    return this._container;
+  }
+  async spawn(command, options = {}) {
+    const container = this.container;
+    const mergedEnv = { ...this.env, ...options.env };
+    const envArray = Object.entries(mergedEnv).filter((entry) => entry[1] !== void 0).map(([k, v]) => `${k}=${v}`);
+    const exec = await container.exec({
+      Cmd: ["sh", "-c", command],
+      AttachStdout: true,
+      AttachStderr: true,
+      AttachStdin: true,
+      Tty: false,
+      Env: envArray.length > 0 ? envArray : void 0,
+      WorkingDir: options.cwd
+    });
+    const stream = await exec.start({ hijack: true, stdin: true });
+    const startTime = Date.now();
+    const handle = new DockerProcessHandle(exec, container, startTime, stream, options);
+    handle._setExecStream(stream);
+    const waitPromise = new Promise((resolve) => {
+      const buffer = [];
+      stream.on("data", (chunk) => {
+        buffer.push(chunk);
+        let combined = Buffer.concat(buffer);
+        buffer.length = 0;
+        while (combined.length >= 8) {
+          const type = combined[0];
+          const size = combined.readUInt32BE(4);
+          if (combined.length < 8 + size) {
+            buffer.push(combined);
+            break;
+          }
+          const payload = combined.subarray(8, 8 + size).toString("utf-8");
+          if (type === 1) {
+            handle.emitStdout(payload);
+          } else if (type === 2) {
+            handle.emitStderr(payload);
+          }
+          combined = combined.subarray(8 + size);
+        }
+        if (combined.length > 0 && buffer.length === 0) {
+          buffer.push(combined);
+        }
+      });
+      stream.on("end", async () => {
+        try {
+          const info = await exec.inspect();
+          const exitCode = info.ExitCode ?? 1;
+          handle._setExitCode(exitCode);
+          resolve({
+            success: exitCode === 0,
+            exitCode,
+            stdout: handle.stdout,
+            stderr: handle.stderr,
+            executionTimeMs: Date.now() - startTime
+          });
+        } catch {
+          handle._setExitCode(1);
+          resolve({
+            success: false,
+            exitCode: 1,
+            stdout: handle.stdout,
+            stderr: handle.stderr,
+            executionTimeMs: Date.now() - startTime
+          });
+        }
+      });
+      stream.on("close", () => {
+        if (handle.exitCode !== void 0) return;
+        if (!handle._killed) return;
+        handle._setExitCode(137);
+        resolve({
+          success: false,
+          exitCode: 137,
+          stdout: handle.stdout,
+          stderr: handle.stderr,
+          executionTimeMs: Date.now() - startTime
+        });
+      });
+      stream.on("error", () => {
+        if (handle.exitCode !== void 0) return;
+        handle._setExitCode(1);
+        resolve({
+          success: false,
+          exitCode: 1,
+          stdout: handle.stdout,
+          stderr: handle.stderr || "Stream error",
+          executionTimeMs: Date.now() - startTime
+        });
+      });
+    });
+    const resolvedTimeout = options.timeout ?? this._defaultTimeout;
+    if (resolvedTimeout > 0) {
+      const timeoutMs = resolvedTimeout;
+      const timer = setTimeout(() => {
+        if (handle.exitCode === void 0) {
+          handle._killed = true;
+          handle.kill().catch(() => {
+          });
+          handle._destroyStream();
+        }
+      }, timeoutMs);
+      void waitPromise.then(() => clearTimeout(timer));
+    }
+    handle._setWaitPromise(waitPromise);
+    this._tracked.set(handle.pid, handle);
+    return handle;
+  }
+  /** Clear all tracked process handles and release the container reference (e.g., after container stop/destroy) */
+  reset() {
+    this._tracked.clear();
+    this._container = null;
+  }
+  async list() {
+    const results = [];
+    for (const [pid, handle] of this._tracked) {
+      results.push({
+        pid,
+        command: handle.command,
+        running: handle.exitCode === void 0,
+        exitCode: handle.exitCode
+      });
+    }
+    return results;
+  }
+};
+
+// src/sandbox/index.ts
+var LOG_PREFIX = "[DockerSandbox]";
+var DockerSandbox = class extends workspace.MastraSandbox {
+  id;
+  name = "DockerSandbox";
+  provider = "docker";
+  status = "pending";
+  /** Underlying Docker client */
+  _docker;
+  /** Container reference (set after start) */
+  _container = null;
+  /** Configuration */
+  _image;
+  _command;
+  _env;
+  _volumes;
+  _network;
+  _privileged;
+  _workingDir;
+  _labels;
+  _instructionsOverride;
+  constructor(options = {}) {
+    const processManager = new DockerProcessManager({
+      env: options.env ?? {},
+      defaultTimeout: options.timeout ?? 3e5
+    });
+    super({
+      ...options,
+      name: "DockerSandbox",
+      processes: processManager
+    });
+    this.id = options.id ?? this._generateId();
+    this._image = options.image ?? "node:22-slim";
+    this._command = options.command ?? ["sleep", "infinity"];
+    this._env = options.env ?? {};
+    this._volumes = options.volumes ?? {};
+    this._network = options.network;
+    this._privileged = options.privileged ?? false;
+    this._workingDir = options.workingDir ?? "/workspace";
+    this._labels = {
+      ...options.labels,
+      "mastra.sandbox": "true",
+      "mastra.sandbox.id": this.id
+    };
+    this._instructionsOverride = options.instructions;
+    this._docker = new Docker__default.default(options.dockerOptions);
+  }
+  /**
+   * Get the underlying Docker container for direct access.
+   * @throws {SandboxNotReadyError} If the sandbox has not been started.
+   */
+  get container() {
+    if (!this._container) {
+      throw new workspace.SandboxNotReadyError(this.id);
+    }
+    return this._container;
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  async start() {
+    this.logger.debug(`${LOG_PREFIX} Starting sandbox ${this.id}...`);
+    const existing = await this._findExistingContainer();
+    if (existing) {
+      this.logger.debug(`${LOG_PREFIX} Found existing container ${existing.Id}`);
+      this._container = this._docker.getContainer(existing.Id);
+      const info = await this._container.inspect();
+      const actualState = info.State?.Running ? "running" : "stopped";
+      if (actualState !== "running") {
+        this.logger.debug(`${LOG_PREFIX} Container exists but not running (${actualState}), starting...`);
+        await this._container.start();
+      }
+      this.processes.setContainer(this._container);
+      this.logger.debug(`${LOG_PREFIX} Reconnected to container ${existing.Id}`);
+      return;
+    }
+    await this._ensureImage();
+    const envArray = Object.entries(this._env).map(([k, v]) => `${k}=${v}`);
+    const binds = Object.entries(this._volumes).map(([host, container]) => `${host}:${container}`);
+    this.logger.debug(`${LOG_PREFIX} Creating container with image ${this._image}...`);
+    this._container = await this._docker.createContainer({
+      Image: this._image,
+      Cmd: this._command,
+      Env: envArray,
+      WorkingDir: this._workingDir,
+      Labels: this._labels,
+      HostConfig: {
+        Binds: binds.length > 0 ? binds : void 0,
+        NetworkMode: this._network,
+        Privileged: this._privileged
+      },
+      // Keep stdin open for interactive use
+      OpenStdin: true,
+      Tty: false
+    });
+    await this._container.start();
+    this.processes.setContainer(this._container);
+    this.logger.debug(`${LOG_PREFIX} Container started: ${this._container.id}`);
+  }
+  async stop() {
+    const container = await this._resolveContainer();
+    if (!container) return;
+    this.logger.debug(`${LOG_PREFIX} Stopping container ${container.id}...`);
+    try {
+      await container.stop({ t: 10 });
+    } catch (error) {
+      if (!isContainerNotRunningError(error)) {
+        throw error;
+      }
+    }
+    this.processes.reset();
+    this.logger.debug(`${LOG_PREFIX} Container stopped`);
+  }
+  async destroy() {
+    const container = await this._resolveContainer();
+    if (!container) return;
+    this.logger.debug(`${LOG_PREFIX} Destroying container ${container.id}...`);
+    try {
+      await container.remove({ force: true, v: true });
+    } catch (error) {
+      if (!isContainerNotFoundError(error)) {
+        throw error;
+      }
+    }
+    this.processes.reset();
+    this._container = null;
+    this.logger.debug(`${LOG_PREFIX} Container destroyed`);
+  }
+  // ---------------------------------------------------------------------------
+  // Instructions
+  // ---------------------------------------------------------------------------
+  getInstructions(opts) {
+    const defaultInstructions = [
+      `You are working inside a Docker container (image: ${this._image}).`,
+      `The working directory is ${this._workingDir}.`,
+      "You can execute shell commands using executeCommand().",
+      "You can spawn background processes using processes.spawn()."
+    ].join("\n");
+    if (this._instructionsOverride === void 0) return defaultInstructions;
+    if (typeof this._instructionsOverride === "string") return this._instructionsOverride;
+    return this._instructionsOverride({ defaultInstructions, requestContext: opts?.requestContext });
+  }
+  // ---------------------------------------------------------------------------
+  // Info
+  // ---------------------------------------------------------------------------
+  async getInfo() {
+    const info = {
+      id: this.id,
+      name: this.name,
+      provider: this.provider,
+      status: this.status,
+      createdAt: /* @__PURE__ */ new Date(),
+      metadata: {
+        image: this._image,
+        workingDir: this._workingDir,
+        labels: this._labels
+      }
+    };
+    if (this._container) {
+      try {
+        const inspect = await this._container.inspect();
+        info.createdAt = new Date(inspect.Created);
+        info.metadata = {
+          ...info.metadata,
+          containerId: inspect.Id,
+          containerName: inspect.Name,
+          state: inspect.State.Status
+        };
+      } catch {
+      }
+    }
+    return info;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  _generateId() {
+    return `docker-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+  /**
+   * 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.
+   */
+  async _resolveContainer() {
+    if (this._container) return this._container;
+    const existing = await this._findExistingContainer();
+    if (!existing) return null;
+    this._container = this._docker.getContainer(existing.Id);
+    return this._container;
+  }
+  /**
+   * Find an existing container matching this sandbox's ID via labels.
+   */
+  async _findExistingContainer() {
+    try {
+      const containers = await this._docker.listContainers({
+        all: true,
+        filters: {
+          label: [`mastra.sandbox.id=${this.id}`]
+        }
+      });
+      return containers[0] ?? null;
+    } catch (error) {
+      this.logger.debug(
+        `${LOG_PREFIX} Failed to list containers: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw error;
+    }
+  }
+  /**
+   * Ensure the Docker image is available locally. Pulls if needed.
+   */
+  async _ensureImage() {
+    try {
+      await this._docker.getImage(this._image).inspect();
+      this.logger.debug(`${LOG_PREFIX} Image ${this._image} available locally`);
+    } catch (error) {
+      if (!isImageNotFoundError(error)) {
+        throw error;
+      }
+      this.logger.debug(`${LOG_PREFIX} Pulling image ${this._image}...`);
+      try {
+        const stream = await this._docker.pull(this._image);
+        await new Promise((resolve, reject) => {
+          this._docker.modem.followProgress(stream, (err) => {
+            if (err) reject(err);
+            else resolve();
+          });
+        });
+        this.logger.debug(`${LOG_PREFIX} Image ${this._image} pulled successfully`);
+      } catch (error2) {
+        throw new workspace.SandboxError(
+          `Failed to pull Docker image '${this._image}': ${error2 instanceof Error ? error2.message : String(error2)}`,
+          "NOT_READY",
+          { image: this._image, reason: "image_pull_failed" }
+        );
+      }
+    }
+  }
+};
+function isContainerNotRunningError(error) {
+  if (error instanceof Error) {
+    return error.message.includes("is not running") || error.message.includes("container already stopped");
+  }
+  return false;
+}
+function isContainerNotFoundError(error) {
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    return msg.includes("no such container") || msg.includes("removal") && msg.includes("is already in progress");
+  }
+  return false;
+}
+function isImageNotFoundError(error) {
+  if (error instanceof Error) {
+    return error.message.toLowerCase().includes("no such image");
+  }
+  return false;
+}
+
+// src/provider.ts
+var dockerSandboxProvider = {
+  id: "docker",
+  name: "Docker Sandbox",
+  description: "Local container sandbox powered by Docker",
+  configSchema: {
+    type: "object",
+    properties: {
+      image: {
+        type: "string",
+        description: "Docker image to use",
+        default: "node:22-slim"
+      },
+      timeout: {
+        type: "number",
+        description: "Default command timeout in milliseconds",
+        default: 3e5
+      },
+      env: {
+        type: "object",
+        description: "Environment variables",
+        additionalProperties: { type: "string" }
+      },
+      volumes: {
+        type: "object",
+        description: "Host-to-container bind mounts (host path \u2192 container path)",
+        additionalProperties: { type: "string" }
+      },
+      network: {
+        type: "string",
+        description: "Docker network to join"
+      },
+      workingDir: {
+        type: "string",
+        description: "Working directory inside the container",
+        default: "/workspace"
+      },
+      privileged: {
+        type: "boolean",
+        description: "Run in privileged mode",
+        default: false
+      }
+    }
+  },
+  createSandbox: (config) => new DockerSandbox(config)
+};
+
+exports.DockerProcessManager = DockerProcessManager;
+exports.DockerSandbox = DockerSandbox;
+exports.dockerSandboxProvider = dockerSandboxProvider;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map