S008: Docker Manager

Overview

The Docker Manager handles the full lifecycle of agent containers within outcalld. It uses the bollard crate to communicate with the Docker Engine API — creating, starting, monitoring, stopping, and removing containers with the correct security constraints enforced at creation time.

Every agent container is created with a deterministic set of constraints:

• Attached only to an inspected network backed by the daemon's exact Outcall bridge (S002)
• Optional agent.sock and outcall-agent helper mounts for shim-based workloads (S004/S005)
• HTTP_PROXY / HTTPS_PROXY env vars pointed at the HTTP proxy (S006)
• DNS resolver pointed at the DNS filter (S007)
• Numeric non-root process identity, read-only root, dropped capabilities, no-new-privileges, and fixed PID limit
• Explicit Docker network mode, Docker init, and daemon-owned DNS options
• The host API, Docker, and containerd control sockets are never exposed

Control-socket protection is a critical security invariant. Before Bollard issues the Docker API call, Outcall checks lexical and canonical bind-source paths, catches symlinks, and rejects parent mounts that would expose a protected socket. Bind destinations cannot cover the helper shim, agent socket, or resolver configuration. The daemon also inspects the selected network's driver and bridge name; an outcall- prefix alone is not trusted.

Container naming

Callers may supply an exact operator-visible name. Omitted names default to an outcall- prefix plus 8 random hex characters. Discovery and cleanup use the managed-by=outcalld label, not a naming convention. Recipe runtimes provide the higher-level <project>-N naming policy.

Lifecycle

create → start → monitor → stop → remove

The Docker Manager runs as a Tokio task inside outcalld. There is no separate process. The host operator manages containers through the outcall CLI and the outcalld host API. Startup uses a bounded Docker ping so a client endpoint that exists but does not respond is reported as degraded rather than initialized. Lifecycle operations require the managed label and use the inspected immutable Docker ID.

User Scenarios

S008-US-001 [P1] As a host operator, I want to create agent containers with security constraints enforced so that agents cannot access the host surface.

S008-US-002 [P1] As a host operator, I want to list running agent containers so that I can see what is active.

S008-US-003 [P1] As a host operator, I want to stop and remove agent containers so that I can clean up resources.

S008-US-004 [P1] As a host operator, I want the host socket to never be mounted into containers so that agents cannot escalate to the host API.

S008-US-005 [P2] As a host operator, I want to inspect a specific container so that I can debug issues.

S008-US-006 [P1] As a host operator, I want containers to survive daemon restarts so that running workloads are not disrupted.

S008-US-007 [P2] As a host operator, I want to pull images before creating containers so that the create step does not block on network I/O.

Requirements Summary

Out of Scope

• Network creation/destruction — handled by S002
• Bridge management — handled by S001
• Rule evaluation — handled by S003
• Agent API protocol — handled by S004
• Shim binary behavior — handled by S005
• HTTP proxy behavior — handled by S006
• DNS filter behavior — handled by S007
• Container orchestration (scheduling, scaling, rolling updates)
• Image building — operators provide pre-built images
• Volume management beyond the required bind mounts
• TLS or authentication on the host socket
• Inter-container networking beyond outcall network attachment
• GPU passthrough or device mounting

Cross-Spec Dependencies

• Depends on: S001 (bridge must be up)
• Depends on: S002 (network must exist for container attachment)
• Depends on: S004 (agent.sock path for bind mount)
• Depends on: S005 (shim binary path for bind mount)
• Depends on: S006 (proxy address for env var injection)
• Depends on: S007 (DNS resolver address for container config)
• Required by: Host operators managing agent workloads

Shared Types (outcall-api)

Constants

pub const CONTAINER_PREFIX: &str = "outcall-";
pub const SHIM_CONTAINER_PATH: &str = "/usr/local/bin/outcall";
pub const AGENT_SOCKET_CONTAINER_PATH: &str = "/run/outcall/agent.sock";
pub const DEFAULT_STOP_TIMEOUT_SECS: i64 = 10;
pub const DEFAULT_MEMORY_LIMIT: i64 = 512 * 1024 * 1024;
pub const MIN_MEMORY_LIMIT: i64 = 6 * 1024 * 1024;
pub const DEFAULT_CPU_SHARES: i64 = 1024;
pub const MIN_CPU_SHARES: i64 = 2;

Types

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerCreateRequest {
    pub image: String,
    pub network: Option<String>,
    pub name: Option<String>,
    pub user: Option<String>,
    pub memory_limit: Option<i64>,
    pub cpu_shares: Option<i64>,
    pub env: Option<Vec<String>>,
    pub cmd: Option<Vec<String>>,
    pub entrypoint: Option<Vec<String>>,
    pub working_dir: Option<String>,
    pub volumes: Option<Vec<String>>,
    pub include_outcall_helper_mounts: Option<bool>,
    pub interactive: Option<bool>,
    pub tty: Option<bool>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerCreateResult {
    pub container_id: String,
    pub name: String,
    pub created: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerInfo {
    pub container_id: String,
    pub name: String,
    pub image: String,
    pub state: String,
    pub network: String,
    pub created_at: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerStopRequest {
    pub name: String,
    pub timeout: Option<i64>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerStopResult {
    pub name: String,
    pub stopped: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerRemoveRequest {
    pub name: String,
    pub force: Option<bool>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerRemoveResult {
    pub name: String,
    pub removed: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerInspectResult {
    pub container_id: String,
    pub name: String,
    pub image: String,
    pub state: String,
    pub network: String,
    pub ip_address: Option<String>,
    pub mounts: Vec<String>,
    pub env: Vec<String>,
    pub created_at: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ImagePullRequest {
    pub image: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ImagePullResult {
    pub image: String,
    pub pulled: bool,
}