Docker Runtime

Relevant source files

• internal/runtime/docker.go
• internal/runtime/docker_integration_test.go
• internal/runtime/docker_test.go
• internal/runtime/none.go
• internal/runtime/none_test.go
• internal/runtime/runtime.go

The DockerRuntime provides a containerized sandbox environment for executing agent commands and evaluating results. It wraps the local docker CLI to manage container lifecycles, ensuring that evaluations run in isolated environments without requiring host bind mounts or privileged access.

Overview and Lifecycle

The DockerRuntime implements the Runtime interface internal/runtime/docker.go59-73 It follows a strict lifecycle managed by the evaluator:

1. Create: Provisions a new container using docker create. It configures the image, entrypoint, network policy, and environment variables internal/runtime/docker.go109-154
2. Start: The container is started immediately during the Create phase to ensure it is ready for subsequent Exec calls internal/runtime/docker.go133-142
3. Operation: Commands are executed via docker exec, and files are moved via docker cp internal/runtime/docker.go54-58
4. Close: The container is removed via docker rm -f. This is skipped if Config.Delete is set to false, allowing manual inspection internal/runtime/docker.go51-52

Container Initialization Logic

The following diagram illustrates the sequence of CLI commands issued during the Create call.

Sequence: Docker Container Provisioning

Sources: internal/runtime/docker.go109-154 internal/runtime/docker.go159-181

Implementation Details

Workspace and File Transfer

The runtime defaults the workspace to /workspace inside the container internal/runtime/docker.go26

• No Bind Mounts: Unlike traditional Docker usage, skill-up does not use -v host mounts. This ensures that the agent cannot accidentally modify the host filesystem internal/runtime/docker.go54-58
• Upload/Download: Files are transferred using docker cp. When UploadFile is called with a relative path, it is automatically joined with the container's workspace path internal/runtime/docker.go235-241 UploadDir and DownloadDir recursively copy trees between the host and container using the same mechanism internal/runtime/docker.go252-291

Network Policies

The runtime supports strict network isolation via the network_policy field in Config:

• deny_all: Appends --network none to the docker create command, completely severing external access internal/runtime/docker.go165-167
• allow_declared: Currently not supported in the Docker runtime because it requires FQDN-level filtering (egress proxies), which is not natively provided by the Docker CLI wrapper internal/runtime/docker.go81-88

Environment Merging

Environment variables are managed at two levels:

1. Persistent Env: Set during docker create via --env flags internal/runtime/docker.go168-170
2. Call-specific Env: Passed to Exec and applied to the specific docker exec invocation internal/runtime/docker.go312-315

Variables are merged literally using mergeIntoEnvBaseline internal/runtime/runtime.go65-73 without shell expansion to maintain consistency across different runtime backends internal/runtime/docker.go394-396

Code Entity Mapping

The following diagram maps the logical runtime actions to the specific Go functions and Docker CLI subcommands they trigger.

Mapping: Runtime Interface to Docker CLI

Sources: internal/runtime/docker.go59-102 internal/runtime/docker.go109-154 internal/runtime/docker.go235-241 internal/runtime/docker.go303-345

Error Classification and Instrumentation

Error Handling

The runtime uses dockerCLIErr to classify failures from the docker binary internal/runtime/docker.go440-456

• Exit Code 125: Often indicates the container name is already in use or the image is missing internal/runtime/docker.go124-126
• Exit Code 127: Indicates the command passed to Exec was not found inside the container.
• Context Timeouts: Operations like Close and rollbackRemove use a detached context with a 30-second dockerCleanupTimeout to ensure cleanup completes even if the parent evaluation context is cancelled internal/runtime/docker.go35-36 internal/runtime/docker.go192-201

Telemetry and OTEL

Every major operation is instrumented with OpenTelemetry (OTEL) spans using the internal/observability package internal/runtime/docker.go21-22:

• Attributes: Spans include attributes like runtime.type="docker", docker.container_id, and docker.image internal/runtime/docker.go420-425
• Tracing: The Exec method creates a span named runtime.exec and records the command and working directory internal/runtime/docker.go303-310

Summary of Configuration

Feature	Implementation
CLI Wrapper	dockerCommandRunner func type internal/runtime/docker.go42
Randomization	6-byte hex suffix for container names internal/runtime/docker.go28
Entrypoint	Defaults to sleep infinity to keep container alive internal/runtime/docker.go173-174
Shell	Always returns linux POSIX shell internal/runtime/docker.go415-417

Sources: internal/runtime/docker.go1-456 internal/runtime/runtime.go1-216