@cuylabs/agent-sandbox-docker

Docker-backed sandbox sessions and execution hosts for @cuylabs/agent-core.

Use this package when you want host-aware tools to run inside Docker instead of on the local machine. The package supports:

• low-level ToolHost adaptation for an existing container via dockerHost()
• higher-level DockerSandboxSession lifecycle for a managed Docker environment with snapshot(), extendTimeout(), and getPreviewUrl() support
• registerDockerHostProvider() for registry-based host discovery

The agent loop, model calls, middleware, and sessions still live in your Node.js process. Only host-backed tool operations are redirected into the container through the ToolHost interface from @cuylabs/agent-core/tool/host.

Package Boundary

@cuylabs/agent-core owns:

• the ToolHost interface
• the SandboxSession interface
• the default localHost()
• the ToolHostRegistry and defaultToolHostRegistry
• the executor path that passes ctx.host into tools

@cuylabs/agent-sandbox-docker owns:

• connecting ToolHost to a running Docker container
• path resolution inside the container
• file and shell operations implemented through Docker exec sessions (with stdin piping for large files)
• DockerSandboxSession class implementing the full SandboxSession contract
• container snapshot via commit(), lease/timeout tracking, and preview URL construction
• optional self-registration into ToolHostRegistry via registerDockerHostProvider()

That same pattern is intended for other host packages too. Docker is one concrete backend implementing the public ToolHost contract from agent-core.

Quick Start

Managed Session (recommended)

import { createAgent } from "@cuylabs/agent-core";
import { createDockerSandboxSession } from "@cuylabs/agent-sandbox-docker";

const sandbox = await createDockerSandboxSession({
  create: {
    image: "node:20",
    workdir: "/workspace",
  },
  timeoutMs: 300_000,     // 5 minute lease
  hostAddress: "localhost", // for preview URLs
});

const agent = createAgent({
  model,
  sandbox,
});

// Snapshot the environment
const snap = await sandbox.snapshot();

// Extend the lease
await sandbox.extendTimeout(60_000);

// Get preview URL for an exposed port
const url = sandbox.getPreviewUrl(3000); // "http://localhost:3000"

// Clean up
await sandbox.stop();

Attach to Existing Container

import { createDockerSandboxSession } from "@cuylabs/agent-sandbox-docker";

const sandbox = await createDockerSandboxSession({
  container: "my-workspace",
  workdir: "/workspace",
});

Low-Level Host Only

If you already manage the container lifecycle yourself:

import { dockerHost } from "@cuylabs/agent-sandbox-docker";

const host = await dockerHost({
  container: "my-sandbox",
  workdir: "/workspace",
});

Registry Integration

import { registerDockerHostProvider } from "@cuylabs/agent-sandbox-docker";
import { defaultToolHostRegistry } from "@cuylabs/agent-core/tool/host";

// Call once at startup
registerDockerHostProvider();

// Then create hosts by name
const host = await defaultToolHostRegistry.create("docker", {
  container: "my-workspace",
});

Start Here

• docs/README.md for the package documentation map
• docs/how-it-works.md for the implementation details
• examples/README.md for a runnable end-to-end example

agent-core keeps the host contract and the default local host. Concrete non-local hosts live in separate packages so they can evolve independently.