Docker extension

Run isolated Python with the official Docker extension for ADK and LangGraph. Harnest manages containers and optional services; you provide a reachable Docker daemon.

Install the extension

From the agent folder:

harnest extensions install docker
# Equivalent: harnest extensions install harnest-extension-docker
harnest env sync .

For local extension development, point the same command at a checkout:

harnest extensions install ../official-extensions/docker --force
harnest env sync .

Harnest validates and copies the package without importing its code. Use Python 3.11 or newer with the current Harnest release. Version 0.4.2 requires Harnest >=1.0.0,<2 and docker>=7.1,<8. The host must provide a reachable Docker daemon.

Declare a Docker sandbox

Create sandbox/python.py. The exported variable must match the filename:

sandbox/python.py

from harnest.extensions.docker import docker, DockerScope
from harnest.sandbox import SandboxBudget, SandboxNetworkPolicy

python = docker.sandbox(
    image="python:3.12-slim@sha256:<approved-digest>",
    network_policy=SandboxNetworkPolicy.none(),
    scope=DockerScope.EXECUTION,
    timeout_seconds=120,
    max_output_bytes=1_048_576,
    budget=SandboxBudget(
        cpu=1.0,
        memory_bytes=512 * 1024 * 1024,
        pids=64,
        scratch_bytes=64 * 1024 * 1024,
    ),
)

Add "python" to each consuming agent’s sandboxes=[...] grant. Call it from an authored tool through context.sandboxes["python"]. Exactly one of image or docker_path is required; prefer an immutable image digest in deployments.

Sandbox configuration

See docker.sandbox configuration for parameters and defaults. Configuration is validated immediately; Docker starts on first execution. See the reference for adapter options and metadata.

Add service containers

Attach bounded services when the primary Python container needs another process:

sandbox/worker.py

from harnest.extensions.docker import docker, DockerScope
from harnest.sandbox import SandboxBudget, SandboxNetworkPolicy

queue = docker.service(
    name="queue",
    image="redis:7-alpine@sha256:<approved-digest>",
    command=["redis-server", "--save", ""],
    ports=[6379],
    readiness=docker.readiness(command=["redis-cli", "ping"]),
    budget=SandboxBudget(memory_bytes=128 * 1024 * 1024),
)

worker = docker.sandbox(
    image="python:3.12-slim@sha256:<approved-digest>",
    services=[queue],
    network=docker.network(internal=True),
    network_policy=SandboxNetworkPolicy.none(),
    scope=DockerScope.SESSION,
)

A private bridge connects the Python container and up to eight services. Use service names or aliases for DNS; declared ports are never published on the host. An internal topology network remains inside the sandbox boundary, so services can communicate when network_policy denies external egress. Use docker.network(internal=False) only with SandboxNetworkPolicy.unrestricted(). That choice gives every topology container the same unrestricted egress authority. Services start in declaration order, each with its own SandboxBudget. Python waits for declared readiness checks. Cleanup removes the primary container, services in reverse order, then the network. Unconfirmed cleanup blocks replacement.

Choose a reuse scope

Scope	Container ownership
`DockerScope.EXECUTION`	Fresh topology for every call; this is the default
`DockerScope.INVOCATION`	Reuse only for the same agent, user, session, and invocation
`DockerScope.SESSION`	Reuse only for the same agent, user, and session

Retained scopes reuse the container and its /tmp scratch files while that identity remains cached, but not live processes or durable storage. Every successful call stops remaining processes. max_scopes defaults to 8 and evicts the least recently used retained container before admitting another identity.

Set network authority

The extension supports SandboxNetworkPolicy.none() and SandboxNetworkPolicy.unrestricted(block_private_networks=False). No-network mode is the default. Exact host or port allowlists, and unrestricted networking with private-network blocking, fail closed because this provider does not yet enforce those controls at Docker’s network boundary. Network policy is provider-enforced authority. Validating a URL in an Agent Tool does not replace it. Use another sandbox provider when a workload requires exact destination enforcement.

Understand deadlines and cleanup

The deadline covers queueing, startup, and execution. Output is bounded during capture. Timeout, cancellation, overflow, or failed startup discards the container instead of reusing it. Cleanup has a separate five-second deadline. Uncertain termination blocks replacement. Inspect dev.harnest.* container labels to identify owned resources. Logs and traces use harnest.extension.name=docker, topology IDs, and service names. They omit commands, environment values, identities, readiness output, and raw Docker errors.

Security boundary

Docker daemon access is highly privileged. Protect its socket or remote API, restrict who can configure this extension, and use trusted digest-pinned images. Containers run as a non-root user with a read-only root filesystem, dropped capabilities, no-new-privileges, bounded /tmp, and no host mounts. Docker still shares the host kernel; choose a stronger provider for higher-risk isolation. The extension does not transfer input or output files. Use stdout or a provider with an explicit file contract. See Sandboxing for agent grants, authored-tool usage, custom providers, and failure handling. For all factory methods, topology contracts, and bounds, see the Docker API reference.

Overview

Get started

Harnest Studio

Guides

API reference

Docker extension

Install the extension

Declare a Docker sandbox

Sandbox configuration

Add service containers

Choose a reuse scope

Set network authority

Understand deadlines and cleanup

Security boundary

​Install the extension

​Declare a Docker sandbox

​Sandbox configuration

​Add service containers

​Choose a reuse scope

​Set network authority

​Understand deadlines and cleanup

​Security boundary

Install the extension

Declare a Docker sandbox

Sandbox configuration

Add service containers

Choose a reuse scope

Set network authority

Understand deadlines and cleanup

Security boundary