---
title: Docker API
description: Generated public TypeScript reference for @relkit/docker.
search:
  exclude: true
sidebar:
  icon: braces
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [docker](/docs/api/integrations/docker#docker)

For configuration and examples, read [bindings](/docs/modules/jobs/bindings), [docker](/docs/modules/jobs/docker), [integrations](/docs/modules/integrations).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images), [cache product prices](/guides/caching/cache-product-prices).

## Public imports

- `@relkit/docker` — 1 exports
- `@relkit/docker/runtime` — 16 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                     | Kind  | Import from              | Example                                                                                                             |
| --------------------------------------------------------------------------------------- | ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| [createDockerClient](/docs/api/integrations/docker#createdockerclient)                  | Value | `@relkit/docker/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L36)  |
| [createDockerMaterializer](/docs/api/integrations/docker#createdockermaterializer)      | Value | `@relkit/docker/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L37)  |
| [docker](/docs/api/integrations/docker#docker)                                          | Value | `@relkit/docker`         | [API example](/docs/api/integrations/docker#docker)                                                                 |
| [DockerClient](/docs/api/integrations/docker#dockerclient-interface)                    | Type  | `@relkit/docker/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L170) |
| [DockerClientOptions](/docs/api/integrations/docker#dockerclientoptions-interface)      | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerCommandOptions](/docs/api/integrations/docker#dockercommandoptions-interface)    | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerCommandRequest](/docs/api/integrations/docker#dockercommandrequest-interface)    | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerCommandResult](/docs/api/integrations/docker#dockercommandresult-interface)      | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerCommandRunner](/docs/api/integrations/docker#dockercommandrunner-type-alias)     | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerContainer](/docs/api/integrations/docker#dockercontainer-interface)              | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerEngineError](/docs/api/integrations/docker#dockerengineerror-class)              | Value | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerEngineErrorCode](/docs/api/integrations/docker#dockerengineerrorcode-type-alias) | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerEngineInfo](/docs/api/integrations/docker#dockerengineinfo-interface)            | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerHealthOptions](/docs/api/integrations/docker#dockerhealthoptions-interface)      | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [dockerMaterializer](/docs/api/integrations/docker#dockermaterializer)                  | Value | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerVolume](/docs/api/integrations/docker#dockervolume-interface)                    | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [randomLoopbackPort](/docs/api/integrations/docker#randomloopbackport-1)                | Value | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |

## `index.ts`

### docker

Selects an adapter's declared local recipe without contacting Docker.

**Example**

```ts
import { docker } from "@relkit/docker";
import { redis } from "@relkit/redis";

const cache = docker(redis());
```

**Signature**

```ts
declare const docker: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => LocalProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/index.ts#L20)

Since v0.2.0

## `docker-client.ts`

### createDockerClient

**Signature**

```ts
declare const createDockerClient: (options?: DockerClientOptions) => DockerClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-client.ts#L25)

### randomLoopbackPort

**Signature**

```ts
declare const randomLoopbackPort: (containerPort: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-client.ts#L177)

## `docker-composite-support.ts`

### argument

**Signature**

```ts
declare const argument: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L82)

### bindMountArguments

**Signature**

```ts
declare const bindMountArguments: (
  mounts: readonly LocalServiceBindMount[] | undefined,
) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L65)

### compositeLabels

**Signature**

```ts
declare const compositeLabels: (values: Readonly<Record<string, string>>) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L24)

### compositeSignal

**Signature**

```ts
declare const compositeSignal: (request: LocalServiceStartRequest) => {
  readonly signal?: AbortSignal;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L48)

### environmentArguments

**Signature**

```ts
declare const environmentArguments: (
  values: Readonly<Record<string, string>> | undefined,
) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L87)

### healthArgs

**Signature**

```ts
declare const healthArgs: (
  command: readonly string[],
  interval: number,
  timeout: number,
  retries: number,
) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L30)

### inspectNetwork

**Signature**

```ts
declare const inspectNetwork: (
  client: DockerClient,
  networkName: string,
  request: LocalServiceStartRequest,
) => Promise<Readonly<Record<string, string>> | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L106)

### mountPath

**Signature**

```ts
declare const mountPath: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L59)

### owned

**Signature**

```ts
declare const owned: (
  actual: Readonly<Record<string, string>>,
  expected: Readonly<Record<string, string>>,
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L129)

### positive

**Signature**

```ts
declare const positive: (value: number) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L100)

### resourceName

**Signature**

```ts
declare const resourceName: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L54)

### volumeNames

**Signature**

```ts
declare const volumeNames: (
  serviceName: string,
  requested: Readonly<Record<string, string>> | undefined,
  recipe: NormalizedLocalServiceRecipe,
) => Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L8)

## `docker-composite-unit.ts`

### reusedUnit

**Signature**

```ts
declare const reusedUnit: (
  existing: LocalServiceInstance,
  unit: NormalizedLocalServiceUnit,
  serviceName: string,
) => LocalServiceInstance;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-unit.ts#L20)

### startUnit

**Signature**

```ts
declare const startUnit: (
  client: DockerClient,
  request: LocalServiceStartRequest,
  recipe: NormalizedLocalServiceRecipe,
  unit: NormalizedLocalServiceUnit,
  networkName: string,
  volumes: Readonly<Record<string, string>>,
  gatewayAddress?: string,
) => Promise<LocalServiceInstance>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-unit.ts#L44)

## `docker-composite.ts`

### startComposite

**Signature**

```ts
declare const startComposite: (
  client: DockerClient,
  request: LocalServiceStartRequest,
  gatewayAddress?: string,
) => Promise<LocalServiceInstance>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite.ts#L26)

## `docker-health.ts`

### healthTimeout

**Signature**

```ts
declare const healthTimeout: (id: string) => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-health.ts#L72)

### publishedPortArguments

**Signature**

```ts
declare const publishedPortArguments: (
  containerPort: number,
  gatewayAddress?: string,
  hostPort?: number,
) => Promise<string[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-health.ts#L14)

### randomLoopbackPort

**Signature**

```ts
declare const randomLoopbackPort: (containerPort: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-health.ts#L4)

### wait

**Signature**

```ts
declare const wait: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-health.ts#L79)

## `docker-inspect.ts`

### parseContainers

**Signature**

```ts
declare const parseContainers: (source: string) => readonly DockerContainer[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-inspect.ts#L4)

### parseVolumes

**Signature**

```ts
declare const parseVolumes: (source: string) => readonly DockerVolume[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-inspect.ts#L31)

## `docker-materializer-support.ts`

### argument

**Signature**

```ts
declare const argument: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L54)

### duration

**Signature**

```ts
declare const duration: (value: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L45)

### healthCommand

**Signature**

```ts
declare const healthCommand: (values: readonly string[]) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L23)

### labelArguments

**Signature**

```ts
declare const labelArguments: (values: Readonly<Record<string, string>>) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L1)

### labelKey

**Signature**

```ts
declare const labelKey: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L18)

### labels

**Signature**

```ts
declare const labels: (values: Readonly<Record<string, string>>) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L13)

### mountPath

**Signature**

```ts
declare const mountPath: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L40)

### name

**Signature**

```ts
declare const name: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L35)

### networkLabelFilters

**Signature**

```ts
declare const networkLabelFilters: (values: Readonly<Record<string, string>>) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L7)

### positive

**Signature**

```ts
declare const positive: (value: number) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L49)

### resourceName

**Signature**

```ts
declare const resourceName: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L30)

## `docker-materializer.ts`

### createDockerMaterializer

**Signature**

```ts
declare const createDockerMaterializer: (
  options?: DockerClientOptions & {
    readonly client?: DockerClient;
    readonly gatewayAddress?: string;
  },
) => LocalServiceMaterializerRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer.ts#L25)

## `docker-runner.ts`

### dockerCommandRunner

**Signature**

```ts
declare const dockerCommandRunner: (executable?: string) => DockerCommandRunner;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-runner.ts#L8)

## `docker-types.ts`

### DockerClient (interface)

**Signature**

```ts
export interface DockerClient {
  readonly discover: (signal?: AbortSignal) => Promise<DockerEngineInfo>;
  readonly command: (
    arguments_: readonly string[],
    operation: string,
    options?: DockerCommandOptions,
  ) => Promise<string>;
  readonly containers: (
    labels?: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<readonly DockerContainer[]>;
  readonly volumes: (
    labels?: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<readonly DockerVolume[]>;
  readonly inspectContainer: (id: string, signal?: AbortSignal) => Promise<DockerContainer>;
  readonly waitForHealthy: (id: string, options?: DockerHealthOptions) => Promise<DockerContainer>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L75)

### DockerClientOptions (interface)

**Signature**

```ts
export interface DockerClientOptions {
  readonly executable?: string;
  readonly run?: DockerCommandRunner;
  readonly maxOutputBytes?: number;
  readonly commandTimeoutMs?: number;
  readonly now?: () => number;
  readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L66)

### DockerCommandOptions (interface)

**Signature**

```ts
export interface DockerCommandOptions {
  readonly signal?: AbortSignal;
  readonly timeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L22)

### DockerCommandRequest (interface)

**Signature**

```ts
export interface DockerCommandRequest extends DockerCommandOptions {
  readonly maxOutputBytes: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L27)

### DockerCommandResult (interface)

**Signature**

```ts
export interface DockerCommandResult {
  readonly exitCode: number;
  readonly stdout: string;
  readonly stderr: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L31)

### DockerCommandRunner (type alias)

**Signature**

```ts
type DockerCommandRunner = (
  command: readonly string[],
  options: DockerCommandRequest,
) => Promise<DockerCommandResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L37)

### DockerContainer (interface)

**Signature**

```ts
export interface DockerContainer {
  readonly id: string;
  readonly name: string;
  readonly labels: Readonly<Record<string, string>>;
  readonly state: string;
  readonly health?: "starting" | "healthy" | "unhealthy";
  readonly ports: Readonly<Record<string, number>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L46)

### DockerEngineError (class)

**Signature**

```ts
declare class DockerEngineError { constructor(
    readonly code: DockerEngineErrorCode,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L12)

### DockerEngineErrorCode (type alias)

**Signature**

```ts
type DockerEngineErrorCode =
  | "RELKIT_DOCKER_ARGUMENT_INVALID"
  | "RELKIT_DOCKER_UNAVAILABLE"
  | "RELKIT_DOCKER_COMMAND_FAILED"
  | "RELKIT_DOCKER_COMMAND_TIMEOUT"
  | "RELKIT_DOCKER_OUTPUT_LIMIT"
  | "RELKIT_DOCKER_RESPONSE_INVALID"
  | "RELKIT_DOCKER_HEALTH_FAILED"
  | "RELKIT_DOCKER_HEALTH_TIMEOUT"
  | "RELKIT_DOCKER_CANCELLED";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L1)

### DockerEngineInfo (interface)

**Signature**

```ts
export interface DockerEngineInfo {
  readonly version: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L42)

### DockerHealthOptions (interface)

**Signature**

```ts
export interface DockerHealthOptions {
  readonly timeoutMs?: number;
  readonly pollIntervalMs?: number;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L60)

### DockerVolume (interface)

**Signature**

```ts
export interface DockerVolume {
  readonly name: string;
  readonly labels: Readonly<Record<string, string>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L55)

## `docker-validation.ts`

### cancelled

**Signature**

```ts
declare const cancelled: () => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L68)

### invalidArgument

**Signature**

```ts
declare const invalidArgument: () => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L60)

### invalidResponse

**Signature**

```ts
declare const invalidResponse: () => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L64)

### labelFilters

**Signature**

```ts
declare const labelFilters: (labels: Readonly<Record<string, string>> | undefined) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L3)

### optionalSignal

**Signature**

```ts
declare const optionalSignal: (signal: AbortSignal | undefined) => DockerCommandOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L56)

### positive

**Signature**

```ts
declare const positive: (value: number, name: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L38)

### requiredText

**Signature**

```ts
declare const requiredText: (value: unknown, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L45)

### resourceLines

**Signature**

```ts
declare const resourceLines: (value: string) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L13)

### responseText

**Signature**

```ts
declare const responseText: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L51)

### validateArgument

**Signature**

```ts
declare const validateArgument: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L30)

### validateArguments

**Signature**

```ts
declare const validateArguments: (values: readonly string[]) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L25)

### validateResourceId

**Signature**

```ts
declare const validateResourceId: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L34)

## `index.ts`

### "./docker-client.js" (namespace export)

Re-exports all named exports from the "./docker-client.js" module.

**Signature**

```ts
export * from "./docker-client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/index.ts#L6)

### "./docker-materializer.js" (namespace export)

Re-exports all named exports from the "./docker-materializer.js" module.

**Signature**

```ts
export * from "./docker-materializer.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/index.ts#L7)

### "./docker-types.js" (namespace export)

Re-exports all named exports from the "./docker-types.js" module.

**Signature**

```ts
export * from "./docker-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/index.ts#L8)

### dockerMaterializer

**Signature**

```ts
declare const dockerMaterializer: Readonly<{
  kind: "local-service-materializer";
  protocolVersion: 1;
  integrationId: "docker";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/index.ts#L10)