weft-docker

Docker runner plugin for Weft.

This extension adds the docker runner via the weft.runners entry-point group. It supports one-shot command TaskSpecs and the Docker-backed one-shot provider CLI agent lane documented in Weft's agent runtime spec.

Security note. Weft assumes user-level trust (see docs/specifications/00-Overview_and_Architecture.md). spec.runner.options.docker_args is a passthrough to docker run: managed flags (--memory, --network, --volume, …) are validated against collisions, but escape-hatch flags such as --privileged, --cap-add, --security-opt, --pid=host, and -v /:/host are not blocked. A task author who can set docker_args can therefore weaken or defeat the container isolation; treat docker_args as equivalent to local docker run access, not as a sandbox boundary.

Current host support:

Linux: supported
macOS: supported
Windows: not currently supported

Container Profiles

Command tasks can select a project-local Docker container profile through spec.runner.options.container_profile. Profiles are useful when the Weft manager runs on the host but the task must run inside a Docker network where service names such as db, redis, or internal-api resolve.

TaskSpec shape:

{
  "spec": {
    "type": "command",
    "process_target": "python3",
    "args": ["-m", "my_project.probe"],
    "runner": {
      "name": "docker",
      "options": {
        "container_profile": "ops"
      }
    }
  }
}

By default, profiles are loaded from .weft/docker-profiles.toml. A task can override that with spec.runner.options.container_profile_file.

version = 1

# Optional. Relative values are resolved from this file's directory.
root = ".."

[profiles.ops]
image = "ghcr.io/example/project:latest"
network = "project_ops"
mount_workdir = false
container_workdir = "/app/project"
env_from_host = ["OPTIONAL_TOKEN"]
required_env_from_host = ["REQUIRED_TOKEN"]

[profiles.ops.env]
SERVICE_URL = "https://internal-api:8443"

[[profiles.ops.mounts]]
source = "config"
target = "/app/project/config"
read_only = true

Profile values are defaults. Explicit TaskSpec spec.runner.options and spec.env win over profile values. env_from_host forwards named host environment variables when present. required_env_from_host requires the merged task environment to contain the named value, either from host env, profile env, or explicit TaskSpec env.

Relative profile mount and build paths resolve against container_profile_root, then top-level TOML root, then the profile file's directory. Runtime checks for named Docker networks and profile-sourced mount or build paths run only during explicit preflight validation.

Container profiles currently apply to command tasks only. Docker-backed agent tasks continue to use provider-specific image recipes, container runtime descriptors, and work_item_mounts.

Release tag:

weft_docker/vX.Y.Z

Metadata

Release files for weft-docker 0.9.87

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for weft-docker 0.9.87
File	Size	Uploaded
weft_docker-0.9.87.tar.gz	24.2 kB	Oct 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for weft-docker 0.9.87
File	Interpreter	ABI	Platform	Reset
weft_docker-0.9.87-py3-none-any.whl 29.7 kB Oct 16, 2026	Python 3	none	any	Details

Total release size: 53.9 kB

Release files / weft_docker-0.9.87.tar.gz

Download URL	weft_docker-0.9.87.tar.gz
Size	24.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`68f42b0164e0791756b82b0f9f73c265ee9a473859cc2c2dd231cf1e98f9cd8f`
BLAKE2b-256 checksum How to use checksums	`a9c1517507a12275da1516cb60d9b0f10a1e120787d09f2408dd209bbaafc06b`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / weft_docker-0.9.87-py3-none-any.whl

Download URL	weft_docker-0.9.87-py3-none-any.whl
Size	29.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8ad1de1cf19c35cf6f81752483c9c056e449d046c56f583e8adfcde36b61cea4`
BLAKE2b-256 checksum How to use checksums	`552b0847d9dddeb4aad353e665ee412dd1af81c2c0ec168efb02320dfd721a63`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`