docker

Documentation

Overview

Package docker implements the Docker/Podman sandbox driver.

The driver shells out to the `docker` or `podman` CLI rather than embedding a Go SDK — see .plans/on-va-tudier-la-snappy-lemon.md §1a for the rationale (binary size, dual-runtime support, surface stability). The CLI surface used here is the subset both runtimes implement compatibly: `docker run`, `docker create`, `docker start`, `docker exec`, `docker stop`, `docker rm`, `docker image inspect`, `docker pull`.

The driver is opt-in: workflows that don't activate a sandbox never instantiate it, and `iterion sandbox doctor` reports unavailability gracefully so users on hosts without Docker can still run iterion in noop mode.

Index

• Constants
• func Constructor() (sandbox.Driver, error)
• func New() (sandbox.Driver, error)
• type Driver
  • func (d *Driver) Capabilities() sandbox.Capabilities
  • func (d *Driver) Name() string
  • func (d *Driver) Prepare(ctx context.Context, spec sandbox.Spec) (sandbox.PreparedSpec, error)
  • func (d *Driver) Start(ctx context.Context, prepared sandbox.PreparedSpec, info sandbox.RunInfo) (sandbox.Run, error)
  • func (d *Driver) WithLogger(l *iterlog.Logger) *Driver
• type Prepared
  • func (p *Prepared) DriverName() string
  • func (p *Prepared) Spec() sandbox.Spec
• type Run
  • func (r *Run) Cleanup(ctx context.Context) error
  • func (r *Run) Command(ctx context.Context, cmd []string, opts sandbox.ExecOpts) *exec.Cmd
  • func (r *Run) Driver() string
  • func (r *Run) Exec(ctx context.Context, cmd []string, opts sandbox.ExecOpts) (sandbox.ExecResult, error)
  • func (r *Run) Stop(ctx context.Context) error
• type Runtime
  • func Detect() (Runtime, error)

Constants

const DefaultWorkspace = "/workspace"

DefaultWorkspace is the in-container path where the host worktree is bind-mounted. Devcontainer convention. Workflows can override via sandbox.Spec.WorkspaceFolder.

Functions

func Constructor

func Constructor() (sandbox.Driver, error)

Constructor is the sandbox.DriverConstructor hook for registration in sandbox.Factory. The factory falls back to the next candidate (podman, then noop) when this returns ErrUnavailable, so callers do not need to special-case Docker absence.

func New

func New() (sandbox.Driver, error)

New returns a Docker driver bound to the given runtime, or an error when neither docker nor podman are on PATH. The constructor itself is cheap — no images are pulled, no containers created.

The driver starts with a discard logger; callers (engine, doctor) install a real logger via Driver.WithLogger so sandbox events are interleaved with the rest of the run.

Types

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

Driver implements sandbox.Driver for the Docker / Podman runtimes.

func (*Driver) Capabilities

func (d *Driver) Capabilities() sandbox.Capabilities

Capabilities advertises the features the driver supports today. Phase 1 implements image, mounts, env, remote user, and post-create. Build (Dockerfile-at-run-start) and network policy land in later phases.

func (*Driver) Name

func (d *Driver) Name() string

Name returns the underlying runtime ("docker" or "podman").

func (*Driver) Prepare

func (d *Driver) Prepare(ctx context.Context, spec sandbox.Spec) (sandbox.PreparedSpec, error)

Prepare validates the spec, ensures the requested image is present on the host (pulling it if missing), and returns an opaque [PreparedSpec] consumed by Driver.Start. It is the ctx-aware "do all the slow IO before allocating a container" hook.

func (*Driver) Start

func (d *Driver) Start(ctx context.Context, prepared sandbox.PreparedSpec, info sandbox.RunInfo) (sandbox.Run, error)

Start creates and starts a long-lived container holding the run for its lifetime. The caller invokes Run.Command / Run.Exec for each delegate (claude_code, tool node) — startup cost is amortised across every invocation in the run.

func (*Driver) WithLogger

func (d *Driver) WithLogger(l *iterlog.Logger) *Driver

WithLogger returns a copy of the driver bound to a specific logger. The default logger discards output; engine integration installs the run's logger so sandbox events are interleaved with the rest of the run.

type Prepared

type Prepared struct {
	// contains filtered or unexported fields
}

Prepared is the docker driver's sandbox.PreparedSpec implementation.

func (*Prepared) DriverName

func (p *Prepared) DriverName() string

DriverName implements sandbox.PreparedSpec.

func (*Prepared) Spec

func (p *Prepared) Spec() sandbox.Spec

Spec returns the spec the prepared was built from. Useful for tests and engine-side diagnostics.

type Run

type Run struct {
	// contains filtered or unexported fields
}

Run is the live docker driver sandbox handle.

All Run methods are safe to call concurrently — `docker exec` is itself concurrent-safe and the cleanup mutex serialises lifecycle transitions.

func (*Run) Cleanup

func (r *Run) Cleanup(ctx context.Context) error

Cleanup ensures the container is gone. Containers were created with `--rm` so a graceful Stop already removes them; Cleanup is the fallback for the failure-mode where the container is alive but orphaned (engine crash mid-run, etc.).

func (*Run) Command

func (r *Run) Command(ctx context.Context, cmd []string, opts sandbox.ExecOpts) *exec.Cmd

Command returns an *exec.Cmd that, when started, runs cmd inside the container via `docker exec`. Stdin/Stdout/Stderr on the returned cmd are forwarded transparently to the in-container process by docker itself, so callers can drive streaming I/O exactly as they would for a host subprocess.

Cwd defaults to the workspace folder (the bind-mount target); [ExecOpts.WorkDir] overrides per-call.

Env vars are passed via `docker exec --env KEY=VAL` so the inner process sees them — setting them on the returned exec.Cmd.Env would only affect the host-side `docker exec` driver process, not the inner program.

func (*Run) Driver

func (r *Run) Driver() string

Driver returns the runtime name — "docker" or "podman".

func (*Run) Exec

func (r *Run) Exec(ctx context.Context, cmd []string, opts sandbox.ExecOpts) (sandbox.ExecResult, error)

Exec is a buffered convenience wrapper around Run.Command. See sandbox.Run.Exec for semantics.

func (*Run) Stop

func (r *Run) Stop(ctx context.Context) error

Stop sends SIGTERM via `docker stop` with a short grace period. Idempotent — calling Stop on an already-stopped container is a no-op.

type Runtime

type Runtime string

Runtime identifies which container CLI we shell out to.

const (
	// RuntimeDocker uses the `docker` CLI (Docker Engine, Docker
	// Desktop, Colima, OrbStack — all expose a docker-compatible CLI).
	RuntimeDocker Runtime = "docker"

	// RuntimePodman uses the `podman` CLI. The subset of commands we
	// invoke here is bug-compatible with docker, so callers don't need
	// runtime-specific code paths.
	RuntimePodman Runtime = "podman"
)

func Detect

func Detect() (Runtime, error)

Detect probes the host for an available container runtime, preferring docker over podman (matching the convention of most local dev tools). Returns ("", error) when neither binary is on PATH.