> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/providers/docker.md).

# Docker

Docker provider for ComputeSDK — local containerized sandboxes (Python or Node.js) for development and testing.

## Installation & Setup

```bash
npm install @computesdk/docker
```

This provider is **local** — it talks to a Docker Engine/daemon rather than a hosted API, so there are no credentials to configure. Docker must be installed and running on the host. By default the provider connects over the standard socket, falling back to `DOCKER_HOST` or `/var/run/docker.sock`.

## Usage

```typescript
import { docker } from '@computesdk/docker';

const compute = docker({
  runtime: 'python',
});

// Create sandbox
const sandbox = await compute.sandbox.create();

// Run a command
const result = await sandbox.runCommand('echo "Hello from Docker!"');
console.log(result.stdout); // "Hello from Docker!"

// Clean up
await sandbox.destroy();
```

### Configuration Options

```typescript
interface DockerConfig {
  /** Connection to the Docker daemon (exactly what dockerode accepts). Defaults to socket / DOCKER_HOST. */
  connection?: DockerConnection;
  /** Default image runtime identifier, e.g. 'python' or 'node'. Defaults to 'python'. */
  runtime?: string;
  /** Reported timeout in ms. Defaults to 300000 (5 minutes). */
  timeout?: number;
  /** Default image & pull policy for sandboxes. Defaults to python:3.11-slim / ifNotPresent. */
  image: DockerImage;
  /** Declarative container defaults (workdir, env, ports, resources, etc.). */
  container?: ContainerDefaults;
  /** Raw dockerode container create options merged last. */
  createOptions?: ContainerCreateOptions;
  /** Raw dockerode container start options. */
  startOptions?: ContainerStartOptions;
  /** When the provider should clean up containers it created ('always' | 'onSuccess' | 'never'). */
  cleanup?: CleanupPolicy;
  /** Stream container logs. Defaults to false. */
  streamLogs?: boolean;
}

interface DockerImage {
  /** Image reference, e.g. 'python:3.11-slim'. */
  name: string;
  /** Pull strategy: 'always' | 'ifNotPresent' | 'never'. Defaults to 'ifNotPresent'. */
  pullPolicy?: PullPolicy;
  /** Auth for pulling private images (Engine API AuthConfig shape). */
  auth?: RegistryAuth;
}
```

The provider ships sensible defaults (`defaultDockerConfig`) that are merged with your config, so `docker()` with no arguments works out of the box using `python:3.11-slim` with a `/workspace` working directory and a 512 MB memory limit.

### Supported Operations

| Method       | Supported | Notes                                                                                                                                                |
| ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create`     | ✅         | Only `'python'` or `'node'` runtimes are supported; any other value throws. Pulls the image (per `pullPolicy`) and starts a keep-alive container.    |
| `getById`    | ✅         | Resolves a container by id; returns `null` if it does not exist.                                                                                     |
| `list`       | ✅         | Lists containers labeled `com.computesdk.sandbox`.                                                                                                   |
| `destroy`    | ✅         | Stops and force-removes the container.                                                                                                               |
| `runCommand` | ✅         | Executes via `docker exec` (`/bin/sh -c`).                                                                                                           |
| `getInfo`    | ✅         |                                                                                                                                                      |
| `getUrl`     | ✅         | Builds a URL from the container's published port bindings, or falls back to the container IP. Requires the port to be exposed via `container.ports`. |
| `filesystem` | ✅         | Implemented via shell commands inside the container.                                                                                                 |

### Notes

* Runtime is limited to `'python'` (default `python:3.11-slim`) or `'node'` (default `node:20-alpine`). Passing any other runtime throws.
* Containers are launched with a keep-alive command so they stay running for exec, filesystem, and background use.
* `getUrl` reads published port bindings; set `container.ports` in the config to expose a port on the host.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.computesdk.com/providers/docker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.