> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# harnest.extensions.docker

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Sandbox configuration

| Option | Default | Purpose |
| - | - | - |
| `image` / `docker_path` | None | Select exactly one registry image or local Docker build context |
| `base_url` | Docker SDK default | Connect to an explicitly configured daemon |
| `network_policy` | `none()` | Grant no egress or supported unrestricted egress |
| `services` / `network` | Empty | Declare a private multi-container topology |
| `timeout_seconds` | 300 | Bound queueing, startup, and execution |
| `max_output_bytes` | 1 MiB | Bound captured output while streaming |
| `scope` | `EXECUTION` | Choose execution, invocation, or session reuse |
| `budget` | Harnest defaults | Bound CPU, memory, processes, and scratch space |
| `max_scopes` | 8 | Bound retained invocation or session identities |

## Public API and limits

| API | Role |
| - | - |
| `docker.sandbox(...)` / `docker_sandbox(...)` | Create a portable Docker-backed `Sandbox` |
| `docker.service(...)` | Declare one topology service |
| `docker.network(...)` | Declare the topology bridge and egress boundary |
| `docker.readiness(...)` | Declare a bounded service health command |
| `DockerScope` | Select execution, invocation, or session ownership |
| `DockerService`, `DockerNetwork`, `DockerReadiness` | Immutable topology contracts |
| `DockerSandboxProvider` | Runtime adapter implementing Harnest's sandbox provider contract |

A topology supports up to eight services. Each service allows 16 aliases, 32 declared ports, 64 environment entries, and 64 command arguments; bounded authored string values may use up to 8 KiB. Readiness permits 1 to 100 attempts with finite timing values. Service names and aliases must be unique portable lowercase DNS labels. These checks run before the Docker SDK receives configuration.

## Execution budgets

| Setting | Default and behavior |
| - | - |
| `scope` | `DockerScope.EXECUTION`: remove the topology after every call |
| `DockerScope.INVOCATION` | Reuse only for the same agent, user, session, and invocation |
| `DockerScope.SESSION` | Reuse only for the same agent, user, and session |
| `max_scopes` | `8`: evict the least recently used retained container before exceeding this cap |
| `budget.cpu` | `1.0` CPU, enforced by Docker |
| `budget.memory_bytes` | `512 MiB`, with no additional swap allowance |
| `budget.pids` | `64` processes |
| `budget.scratch_bytes` | `64 MiB` for writable `/tmp`; the root filesystem is read-only |
| `timeout_seconds` | `300`; includes queue waiting and active execution |
| `max_output_bytes` | `1 MiB` combined stdout/stderr, bounded while streaming |
| `network_policy` | `SandboxNetworkPolicy.none()`; uses Docker's `none` network without services or an internal topology bridge with services |
| `image` / `docker_path` | Supply exactly one; custom images must provide `python3` and must not declare volumes |
| `base_url` | Optional Docker daemon URL |

`options` retains the allowlisted parsing/retry fields only for callers explicitly constructing a native ADK adapter with `to_adk_executor()`. Those fields do not change Docker limits or add model tools to named sandbox assignments. Your authored tool decides whether to retry.

## Exports

| Name | Kind |
| - | - |
| [`DOCKER_SANDBOX_CAPABILITIES`](#docker_sandbox_capabilities) | Namespace |
| [`DockerNetwork`](#dockernetwork) | Class |
| [`DockerReadiness`](#dockerreadiness) | Class |
| [`DockerScope`](#dockerscope) | Class |
| [`DockerService`](#dockerservice) | Class |
| [`DockerExtension`](#dockerextension) | Class |
| [`DockerSandboxProvider`](#dockersandboxprovider) | Class |
| [`docker`](#docker) | Namespace |
| [`docker_sandbox`](#docker_sandbox) | Function |
| [`extension`](#extension) | Namespace |

## DOCKER\_SANDBOX\_CAPABILITIES

Advertise network controls a provider enforces below agent code.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import DOCKER_SANDBOX_CAPABILITIES
> ```

### DOCKER\_SANDBOX\_CAPABILITIES.require

```python theme={null}
DOCKER_SANDBOX_CAPABILITIES.require(policy: harnest.sandbox.SandboxNetworkPolicy) -> None
```

Fail closed when this provider cannot enforce requested authority.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `policy` | `harnest.sandbox.SandboxNetworkPolicy` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import DOCKER_SANDBOX_CAPABILITIES
>
> DOCKER_SANDBOX_CAPABILITIES.require(policy=...)
> ```

## DockerNetwork

Configure one extension-owned bridge shared only by this sandbox.

```python theme={null}
DockerNetwork(*, internal: bool = True) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `internal` | `bool` | `True` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `internal` | `bool` | `True` |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerNetwork
>
> network = DockerNetwork()
> ```

## DockerReadiness

Wait for a declared Docker health command before sandbox execution.

```python theme={null}
DockerReadiness(
    *,
    command: tuple[str, ...],
    interval_seconds: float = 1.0,
    timeout_seconds: float = 2.0,
    retries: int = 30,
    start_period_seconds: float = 0.0,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `command` | `tuple[str, ...]` | `—` |
| `interval_seconds` | `float` | `1.0` |
| `timeout_seconds` | `float` | `2.0` |
| `retries` | `int` | `30` |
| `start_period_seconds` | `float` | `0.0` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `command` | `tuple[str, ...]` | Required |
> | `interval_seconds` | `float` | `1.0` |
> | `timeout_seconds` | `float` | `2.0` |
> | `retries` | `int` | `30` |
> | `start_period_seconds` | `float` | `0.0` |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerReadiness
>
> readiness = DockerReadiness(command=...)
> ```

## DockerScope

Choose how long one owned Docker topology may be retained.

```python theme={null}
DockerScope(*values)
```

| Member | Value |
| - | - |
| `EXECUTION` | `'execution'` |
| `INVOCATION` | `'invocation'` |
| `SESSION` | `'session'` |

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import DockerScope
>
> value = DockerScope.EXECUTION
> ```

## DockerService

Declare one bounded service container on the private sandbox network.

```python theme={null}
DockerService(
    *,
    name: str,
    image: str | None = None,
    docker_path: str | None = None,
    command: tuple[str, ...] = (),
    environment: Mapping[str, str] = ...,
    ports: tuple[int, ...] = (),
    aliases: tuple[str, ...] = (),
    readiness: DockerReadiness | None = None,
    budget: SandboxBudget = ...,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `name` | `str` | `—` |
| `image` | `str \| None` | `None` |
| `docker_path` | `str \| None` | `None` |
| `command` | `tuple[str, ...]` | `()` |
| `environment` | `Mapping[str, str]` | `dict()` |
| `ports` | `tuple[int, ...]` | `()` |
| `aliases` | `tuple[str, ...]` | `()` |
| `readiness` | `DockerReadiness \| None` | `None` |
| `budget` | `SandboxBudget` | `SandboxBudget()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `image` | `str \| None` | `None` |
> | `docker_path` | `str \| None` | `None` |
> | `command` | `tuple[str, ...]` | `()` |
> | `environment` | `Mapping[str, str]` | `...` |
> | `ports` | `tuple[int, ...]` | `()` |
> | `aliases` | `tuple[str, ...]` | `()` |
> | `readiness` | `DockerReadiness \| None` | `None` |
> | `budget` | `SandboxBudget` | `...` |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerService
>
> service = DockerService(name=...)
> ```

## DockerExtension

Expose Docker sandbox definitions without owning framework resources.

```python theme={null}
DockerExtension(*args: object, **kwargs: object) -> 'Extension[ContextT]'
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `*args` | `object` | Optional |
> | `**kwargs` | `object` | Optional |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension = DockerExtension()
> ```

### DockerExtension.start

```python theme={null}
async DockerExtension.start(context: 'ExtensionStartContext') -> None
```

Initialize application-scoped resources after dependencies start.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `'ExtensionStartContext'` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension: DockerExtension
> await extension.start(context=...)
> ```

### DockerExtension.stop

```python theme={null}
async DockerExtension.stop() -> None
```

Release application-scoped resources before dependencies stop.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension: DockerExtension
> await extension.stop()
> ```

### DockerExtension.create\_context

```python theme={null}
DockerExtension.create_context(context: ExtensionContext) -> ContextT
```

Adapt the managed invocation base to an extension-specific context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `ExtensionContext` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension: DockerExtension
> result = extension.create_context(context=...)
> ```

### DockerExtension.context

Return the task-local extension context for the active invocation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension: DockerExtension
> value = extension.context
> ```

### DockerExtension.sandbox

```python theme={null}
DockerExtension.sandbox(
    *,
    image: str | None = None,
    docker_path: str | None = None,
    base_url: str | None = None,
    network_policy: SandboxNetworkPolicy | None = None,
    services: tuple[DockerService, ...] | list[DockerService] = (),
    network: DockerNetwork | None = None,
    timeout_seconds: int = 300,
    options: Mapping[str, Any] | None = None,
    metadata: Mapping[str, Any] | None = None,
    max_output_bytes: int = 1048576,
    scope: DockerScope = <DockerScope.EXECUTION: 'execution'>,
    budget: SandboxBudget | None = None,
    max_scopes: int = 8,
) -> Sandbox
```

Create a portable Docker sandbox definition from authored options.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `image` | `str \| None` | `None` |
> | `docker_path` | `str \| None` | `None` |
> | `base_url` | `str \| None` | `None` |
> | `network_policy` | `SandboxNetworkPolicy \| None` | `None` |
> | `services` | `tuple[DockerService, ...] \| list[DockerService]` | `()` |
> | `network` | `DockerNetwork \| None` | `None` |
> | `timeout_seconds` | `int` | `300` |
> | `options` | `Mapping[str, Any] \| None` | `None` |
> | `metadata` | `Mapping[str, Any] \| None` | `None` |
> | `max_output_bytes` | `int` | `1048576` |
> | `scope` | `DockerScope` | `<DockerScope.EXECUTION: 'execution'>` |
> | `budget` | `SandboxBudget \| None` | `None` |
> | `max_scopes` | `int` | `8` |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension: DockerExtension
> sandbox = extension.sandbox()
> ```

### DockerExtension.service

```python theme={null}
DockerExtension.service(
    *,
    name: str,
    image: str | None = None,
    docker_path: str | None = None,
    command: tuple[str, ...] | list[str] = (),
    environment: Mapping[str, str] | None = None,
    ports: tuple[int, ...] | list[int] = (),
    aliases: tuple[str, ...] | list[str] = (),
    readiness: DockerReadiness | None = None,
    budget: SandboxBudget | None = None,
) -> DockerService
```

Declare one bounded service container without contacting Docker.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `image` | `str \| None` | `None` |
> | `docker_path` | `str \| None` | `None` |
> | `command` | `tuple[str, ...] \| list[str]` | `()` |
> | `environment` | `Mapping[str, str] \| None` | `None` |
> | `ports` | `tuple[int, ...] \| list[int]` | `()` |
> | `aliases` | `tuple[str, ...] \| list[str]` | `()` |
> | `readiness` | `DockerReadiness \| None` | `None` |
> | `budget` | `SandboxBudget \| None` | `None` |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension: DockerExtension
> service = extension.service(name=...)
> ```

### DockerExtension.network

```python theme={null}
DockerExtension.network(*, internal: bool = True) -> DockerNetwork
```

Declare the extension-owned bridge that joins a sandbox topology.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `internal` | `bool` | `True` |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension: DockerExtension
> network = extension.network()
> ```

### DockerExtension.readiness

```python theme={null}
DockerExtension.readiness(
    *,
    command: tuple[str, ...] | list[str],
    interval_seconds: float = 1.0,
    timeout_seconds: float = 2.0,
    retries: int = 30,
    start_period_seconds: float = 0.0,
) -> DockerReadiness
```

Declare a bounded Docker health command for one service.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `command` | `tuple[str, ...] \| list[str]` | Required |
> | `interval_seconds` | `float` | `1.0` |
> | `timeout_seconds` | `float` | `2.0` |
> | `retries` | `int` | `30` |
> | `start_period_seconds` | `float` | `0.0` |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerExtension
>
> extension: DockerExtension
> readiness = extension.readiness(command=...)
> ```

## DockerSandboxProvider

Bind one extension-owned Docker backend to its configured network policy.

```python theme={null}
DockerSandboxProvider(backend: Any, network_policy: SandboxNetworkPolicy) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `backend` | `Any` | Required |
> | `network_policy` | `SandboxNetworkPolicy` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerSandboxProvider
>
> provider = DockerSandboxProvider(backend=..., network_policy=...)
> ```

### DockerSandboxProvider.sandbox\_capabilities

Advertise network controls a provider enforces below agent code.

### DockerSandboxProvider.sandbox\_capabilities.require

```python theme={null}
DockerSandboxProvider.sandbox_capabilities.require(policy: harnest.sandbox.SandboxNetworkPolicy) -> None
```

Fail closed when this provider cannot enforce requested authority.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `policy` | `harnest.sandbox.SandboxNetworkPolicy` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerSandboxProvider
>
> provider: DockerSandboxProvider
> provider.sandbox_capabilities.require(policy=...)
> ```

### DockerSandboxProvider.execute

```python theme={null}
DockerSandboxProvider.execute(request: SandboxRequest) -> SandboxResult
```

Reject policy substitution before delegating generic Python execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `request` | `SandboxRequest` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import DockerSandboxProvider
>
> provider: DockerSandboxProvider
> result = provider.execute(request=...)
> ```

### DockerSandboxProvider.close

```python theme={null}
DockerSandboxProvider.close() -> None
```

Release the extension backend when the owning sandbox runtime closes.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import DockerSandboxProvider
>
> provider: DockerSandboxProvider
> provider.close()
> ```

## docker

Expose Docker sandbox definitions without owning framework resources.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import docker
> ```

### docker.start

```python theme={null}
async docker.start(context: 'ExtensionStartContext') -> None
```

Initialize application-scoped resources after dependencies start.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `'ExtensionStartContext'` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import docker
>
> await docker.start(context=...)
> ```

### docker.stop

```python theme={null}
async docker.stop() -> None
```

Release application-scoped resources before dependencies stop.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import docker
>
> await docker.stop()
> ```

### docker.create\_context

```python theme={null}
docker.create_context(context: ExtensionContext) -> ContextT
```

Adapt the managed invocation base to an extension-specific context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `ExtensionContext` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import docker
>
> result = docker.create_context(context=...)
> ```

### docker.context

Return the task-local extension context for the active invocation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import docker
>
> value = docker.context
> ```

### docker.sandbox

```python theme={null}
docker.sandbox(
    *,
    image: str | None = None,
    docker_path: str | None = None,
    base_url: str | None = None,
    network_policy: SandboxNetworkPolicy | None = None,
    services: tuple[DockerService, ...] | list[DockerService] = (),
    network: DockerNetwork | None = None,
    timeout_seconds: int = 300,
    options: Mapping[str, Any] | None = None,
    metadata: Mapping[str, Any] | None = None,
    max_output_bytes: int = 1048576,
    scope: DockerScope = <DockerScope.EXECUTION: 'execution'>,
    budget: SandboxBudget | None = None,
    max_scopes: int = 8,
) -> Sandbox
```

Create a portable Docker sandbox definition from authored options.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `image` | `str \| None` | `None` |
> | `docker_path` | `str \| None` | `None` |
> | `base_url` | `str \| None` | `None` |
> | `network_policy` | `SandboxNetworkPolicy \| None` | `None` |
> | `services` | `tuple[DockerService, ...] \| list[DockerService]` | `()` |
> | `network` | `DockerNetwork \| None` | `None` |
> | `timeout_seconds` | `int` | `300` |
> | `options` | `Mapping[str, Any] \| None` | `None` |
> | `metadata` | `Mapping[str, Any] \| None` | `None` |
> | `max_output_bytes` | `int` | `1048576` |
> | `scope` | `DockerScope` | `<DockerScope.EXECUTION: 'execution'>` |
> | `budget` | `SandboxBudget \| None` | `None` |
> | `max_scopes` | `int` | `8` |
>
> ```python theme={null}
> from harnest.extensions.docker import docker
>
> sandbox = docker.sandbox()
> ```

### docker.service

```python theme={null}
docker.service(
    *,
    name: str,
    image: str | None = None,
    docker_path: str | None = None,
    command: tuple[str, ...] | list[str] = (),
    environment: Mapping[str, str] | None = None,
    ports: tuple[int, ...] | list[int] = (),
    aliases: tuple[str, ...] | list[str] = (),
    readiness: DockerReadiness | None = None,
    budget: SandboxBudget | None = None,
) -> DockerService
```

Declare one bounded service container without contacting Docker.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `image` | `str \| None` | `None` |
> | `docker_path` | `str \| None` | `None` |
> | `command` | `tuple[str, ...] \| list[str]` | `()` |
> | `environment` | `Mapping[str, str] \| None` | `None` |
> | `ports` | `tuple[int, ...] \| list[int]` | `()` |
> | `aliases` | `tuple[str, ...] \| list[str]` | `()` |
> | `readiness` | `DockerReadiness \| None` | `None` |
> | `budget` | `SandboxBudget \| None` | `None` |
>
> ```python theme={null}
> from harnest.extensions.docker import docker
>
> service = docker.service(name=...)
> ```

### docker.network

```python theme={null}
docker.network(*, internal: bool = True) -> DockerNetwork
```

Declare the extension-owned bridge that joins a sandbox topology.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `internal` | `bool` | `True` |
>
> ```python theme={null}
> from harnest.extensions.docker import docker
>
> network = docker.network()
> ```

### docker.readiness

```python theme={null}
docker.readiness(
    *,
    command: tuple[str, ...] | list[str],
    interval_seconds: float = 1.0,
    timeout_seconds: float = 2.0,
    retries: int = 30,
    start_period_seconds: float = 0.0,
) -> DockerReadiness
```

Declare a bounded Docker health command for one service.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `command` | `tuple[str, ...] \| list[str]` | Required |
> | `interval_seconds` | `float` | `1.0` |
> | `timeout_seconds` | `float` | `2.0` |
> | `retries` | `int` | `30` |
> | `start_period_seconds` | `float` | `0.0` |
>
> ```python theme={null}
> from harnest.extensions.docker import docker
>
> readiness = docker.readiness(command=...)
> ```

## docker\_sandbox

Create a lazy Docker sandbox without importing an agent framework.

```python theme={null}
docker_sandbox(
    *,
    image: str | None = None,
    docker_path: str | None = None,
    base_url: str | None = None,
    network_policy: SandboxNetworkPolicy | None = None,
    services: tuple[DockerService, ...] | list[DockerService] = (),
    network: DockerNetwork | None = None,
    timeout_seconds: int = 300,
    options: Mapping[str, Any] | None = None,
    metadata: Mapping[str, Any] | None = None,
    max_output_bytes: int = 1048576,
    scope: DockerScope = <DockerScope.EXECUTION: 'execution'>,
    budget: SandboxBudget | None = None,
    max_scopes: int = 8,
) -> Sandbox
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `image` | `str \| None` | `None` |
> | `docker_path` | `str \| None` | `None` |
> | `base_url` | `str \| None` | `None` |
> | `network_policy` | `SandboxNetworkPolicy \| None` | `None` |
> | `services` | `tuple[DockerService, ...] \| list[DockerService]` | `()` |
> | `network` | `DockerNetwork \| None` | `None` |
> | `timeout_seconds` | `int` | `300` |
> | `options` | `Mapping[str, Any] \| None` | `None` |
> | `metadata` | `Mapping[str, Any] \| None` | `None` |
> | `max_output_bytes` | `int` | `1048576` |
> | `scope` | `DockerScope` | `<DockerScope.EXECUTION: 'execution'>` |
> | `budget` | `SandboxBudget \| None` | `None` |
> | `max_scopes` | `int` | `8` |
>
> ```python theme={null}
> from harnest.extensions.docker import docker_sandbox
>
> sandbox = docker_sandbox()
> ```

## extension

Expose Docker sandbox definitions without owning framework resources.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import extension
> ```

### extension.start

```python theme={null}
async extension.start(context: 'ExtensionStartContext') -> None
```

Initialize application-scoped resources after dependencies start.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `'ExtensionStartContext'` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import extension
>
> await extension.start(context=...)
> ```

### extension.stop

```python theme={null}
async extension.stop() -> None
```

Release application-scoped resources before dependencies stop.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import extension
>
> await extension.stop()
> ```

### extension.create\_context

```python theme={null}
extension.create_context(context: ExtensionContext) -> ContextT
```

Adapt the managed invocation base to an extension-specific context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `ExtensionContext` | Required |
>
> ```python theme={null}
> from harnest.extensions.docker import extension
>
> result = extension.create_context(context=...)
> ```

### extension.context

Return the task-local extension context for the active invocation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.docker import extension
>
> value = extension.context
> ```

### extension.sandbox

```python theme={null}
extension.sandbox(
    *,
    image: str | None = None,
    docker_path: str | None = None,
    base_url: str | None = None,
    network_policy: SandboxNetworkPolicy | None = None,
    services: tuple[DockerService, ...] | list[DockerService] = (),
    network: DockerNetwork | None = None,
    timeout_seconds: int = 300,
    options: Mapping[str, Any] | None = None,
    metadata: Mapping[str, Any] | None = None,
    max_output_bytes: int = 1048576,
    scope: DockerScope = <DockerScope.EXECUTION: 'execution'>,
    budget: SandboxBudget | None = None,
    max_scopes: int = 8,
) -> Sandbox
```

Create a portable Docker sandbox definition from authored options.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `image` | `str \| None` | `None` |
> | `docker_path` | `str \| None` | `None` |
> | `base_url` | `str \| None` | `None` |
> | `network_policy` | `SandboxNetworkPolicy \| None` | `None` |
> | `services` | `tuple[DockerService, ...] \| list[DockerService]` | `()` |
> | `network` | `DockerNetwork \| None` | `None` |
> | `timeout_seconds` | `int` | `300` |
> | `options` | `Mapping[str, Any] \| None` | `None` |
> | `metadata` | `Mapping[str, Any] \| None` | `None` |
> | `max_output_bytes` | `int` | `1048576` |
> | `scope` | `DockerScope` | `<DockerScope.EXECUTION: 'execution'>` |
> | `budget` | `SandboxBudget \| None` | `None` |
> | `max_scopes` | `int` | `8` |
>
> ```python theme={null}
> from harnest.extensions.docker import extension
>
> sandbox = extension.sandbox()
> ```

### extension.service

```python theme={null}
extension.service(
    *,
    name: str,
    image: str | None = None,
    docker_path: str | None = None,
    command: tuple[str, ...] | list[str] = (),
    environment: Mapping[str, str] | None = None,
    ports: tuple[int, ...] | list[int] = (),
    aliases: tuple[str, ...] | list[str] = (),
    readiness: DockerReadiness | None = None,
    budget: SandboxBudget | None = None,
) -> DockerService
```

Declare one bounded service container without contacting Docker.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `image` | `str \| None` | `None` |
> | `docker_path` | `str \| None` | `None` |
> | `command` | `tuple[str, ...] \| list[str]` | `()` |
> | `environment` | `Mapping[str, str] \| None` | `None` |
> | `ports` | `tuple[int, ...] \| list[int]` | `()` |
> | `aliases` | `tuple[str, ...] \| list[str]` | `()` |
> | `readiness` | `DockerReadiness \| None` | `None` |
> | `budget` | `SandboxBudget \| None` | `None` |
>
> ```python theme={null}
> from harnest.extensions.docker import extension
>
> service = extension.service(name=...)
> ```

### extension.network

```python theme={null}
extension.network(*, internal: bool = True) -> DockerNetwork
```

Declare the extension-owned bridge that joins a sandbox topology.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `internal` | `bool` | `True` |
>
> ```python theme={null}
> from harnest.extensions.docker import extension
>
> network = extension.network()
> ```

### extension.readiness

```python theme={null}
extension.readiness(
    *,
    command: tuple[str, ...] | list[str],
    interval_seconds: float = 1.0,
    timeout_seconds: float = 2.0,
    retries: int = 30,
    start_period_seconds: float = 0.0,
) -> DockerReadiness
```

Declare a bounded Docker health command for one service.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `command` | `tuple[str, ...] \| list[str]` | Required |
> | `interval_seconds` | `float` | `1.0` |
> | `timeout_seconds` | `float` | `2.0` |
> | `retries` | `int` | `30` |
> | `start_period_seconds` | `float` | `0.0` |
>
> ```python theme={null}
> from harnest.extensions.docker import extension
>
> readiness = extension.readiness(command=...)
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.