phx-paddock 0.4.0

TOML files

Place a config.toml at ~/.config/paddock/ (user-level) or <project>/.paddock/ (project-level). Both are optional, and the project-level file is off by default until you opt in from your user config:

[config.allowlist]
project_toml = true

true is the blanket grant; a list such as project_toml = ["volumes"] permits only the keys it names. See project-level configuration and the allowlist for what each grant hands a committed file.

A config file looks like this:

agent  = "claude"
image  = "my-claude-image:latest"
network = "my-docker-network"

[volumes]
"/host/path" = "/container/path:ro"

[build]
dockerfile = "images/Dockerfile"
context    = "."
policy     = "daily"

[build.args]
AGENT          = "claude"
PYTHON_VERSION = "3.13"

Config fields

Build sub-table

Environment variables

Six config fields can be set via an environment variable, by uppercasing the field name and prefixing it with PADDOCK_. Nested keys are joined with _:

PADDOCK_AGENT=claude
PADDOCK_BUILD_CONTEXT=.
PADDOCK_BUILD_DOCKERFILE=images/Dockerfile
PADDOCK_BUILD_POLICY=daily
PADDOCK_IMAGE=my-claude-image
PADDOCK_NETWORK=my-docker-network

PADDOCK_CONFIG_FILE=/path/to/extra.toml   # loads an additional TOML file

volumes and build.args have no environment-variable form — set them in a TOML file, or pass --volume / --build-args-KEY=VALUE on the command line. PADDOCK_BUILD_ARGS is ignored rather than rejected. Any other unrecognised PADDOCK_* name is a fatal config error, so a typo stops the run:

[env:foo] Unexpected key "foo".

CLI flags

paddock [FLAGS] [--] [COMMAND...]

--agent AGENT                Agent key (e.g. "claude") or "false" for a shell
--build-args-KEY=VALUE        Build-time ARG (repeatable)
--build-context PATH         Docker build context
--build-dockerfile PATH      Path to Dockerfile
--build-policy POLICY        Build policy (always|daily|if-missing|weekly)
--config-file PATH           Load an additional TOML config file
--dry-run                    Print the docker command and exit without running it
--image IMAGE                Docker image
--network NETWORK            Docker network
--quiet                      Suppress all logging and the docker command printout
--volume HOST:CONTAINER[:MODE]  Extra bind-mount (repeatable)
--workdir PATH               Host path to use as the workspace (default: CWD)

--workdir is resolved to an absolute real path — symlinks followed — before it is used for the [projects] lookup and for the mounts.

paddock exits with the container’s exit status; --dry-run exits 0 and a config error exits 1.

Everything after the first positional argument (or after --) is passed as the container command:

paddock claude --allow-dangerously-skip-permissions --continue
paddock --image=my-claude-image -- --allow-dangerously-skip-permissions --continue

claude

Runs claude inside the container. Mounts ~/.claude from the host to /root/.claude:rw so authentication and configuration persist between sessions.

false (shell)

Runs /bin/bash. Useful for exploring the container environment or running ad-hoc commands without a coding agent.

Adding agents

Additional agents can be registered via the paddock.agents entry-point group in any installed package:

[project.entry-points."paddock.agents"]
my-agent = "mypackage.agents:MyAgent"

Each agent must subclass paddock.agents.BaseAgent and implement get_command() and get_volumes().