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 to an outcall-managed network (S002)
• agent.sock bind-mounted into the container (S004)
• outcall-agent shim bind-mounted at /usr/local/bin/outcall (S005)
• HTTP_PROXY / HTTPS_PROXY env vars pointed at the HTTP proxy (S006)
• DNS resolver pointed at the DNS filter (S007)
• The host socket (host.sock) is never mounted into containers

The host socket protection is the critical security invariant. Bollard enforces this at creation time by validating all bind mounts against a deny list before issuing the Docker API call. If any mount resolves to the host socket path, the create call is rejected before reaching Docker.

Container naming

All agent containers use the outcall-agent- prefix followed by a short random suffix (8 hex characters). The prefix is used for discovery and cleanup.

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.

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-agent-";
pub const SHIM_CONTAINER_PATH: &str = "/usr/local/bin/outcall";
pub const AGENT_SOCK_CONTAINER_PATH: &str = "/run/outcall/agent.sock";
pub const DEFAULT_STOP_TIMEOUT_SECS: u32 = 10;
pub const DEFAULT_MEMORY_LIMIT: u64 = 512 * 1024 * 1024; // 512 MiB
pub const DEFAULT_CPU_SHARES: u64 = 1024;

Types

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerCreateRequest {
    pub image: String,
    pub network: Option<String>,
    pub name: Option<String>,
    pub memory_limit: Option<u64>,
    pub cpu_shares: Option<u64>,
    pub env: Option<Vec<String>>,
    pub cmd: Option<Vec<String>>,
}

#[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<u32>,
}

#[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,
}