S002: Network Management

Overview

Manage the isolated networks that agent containers run on. Every agent container connects to an outcall-managed network where all outbound traffic is governed by the bridge and nftables policy layer. The host operator creates, inspects, and destroys these networks through the outcall CLI and the outcalld host API.

A default network (outcall-default) is created on first use and can be destroyed and recreated at any time. Additional named networks can be created for workload isolation — each network shares the same bridge and nftables policy, but provides a separate address space and container group.

Subnet allocation

Outcall reserves the 10.200.0.0/16 block. This range was chosen because it avoids collisions with Docker (172.17+), Kubernetes (10.96, 10.244), AWS VPCs (10.0-10.10), k3s (10.42-10.43), OpenVPN (10.8), home routers (10.0, 192.168), and Podman (10.88). Each network gets a /24 subnet auto-allocated from this block:

outcall-default    → 10.200.0.0/24   (first available)
outcall-staging    → 10.200.1.0/24   (next available)
outcall-prod       → 10.200.2.0/24   (next available)
...up to 255 networks

Before allocating, outcalld checks both its own records and Docker's live network list to avoid collisions. A specific subnet can be requested with --subnet to override auto-allocation.

User Scenarios

S002-US-001 [P1] As a host operator, I want to create isolated networks for agent containers so that each workload group has its own address space.

S002-US-002 [P1] As a host operator, I want to inspect which containers are connected to each network so that I can manage workload placement.

S002-US-003 [P1] As a host operator, I want to destroy networks I no longer need so that resources are cleaned up.

Requirements Summary

Out of Scope

• Container lifecycle management (start, stop, attach, exec)
• Connecting/disconnecting individual containers to/from a network
• Agent-side API exposure — network management endpoints are host-only
• TLS or authentication on the host socket
• Network policy rules (per-container allow/deny) — handled by bridge + nftables
• DNS configuration within networks
• IPv6 support
• Automated bridge-up before network create

Cross-Spec Dependencies

• Depends on: S001 (bridge must be up before network creation — S002-FR-004)
• Required by: S006, S007, S008

Shared Types (outcall-api)

Constants

pub const NETWORK_PREFIX: &str = "outcall-";
pub const DEFAULT_NETWORK_NAME: &str = "outcall-default";
pub const SUBNET_BLOCK: &str = "10.200.0.0/16";
pub const DEFAULT_SUBNET: &str = "10.200.0.0/24";
pub const DEFAULT_GATEWAY: &str = "10.200.0.1";

Types

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NetworkCreateRequest {
    pub name: Option<String>,
    pub subnet: Option<String>,
    pub gateway: Option<String>,
}

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

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NetworkStatus {
    pub exists: bool,
    pub network_id: Option<String>,
    pub name: String,
    pub subnet: Option<String>,
    pub gateway: Option<String>,
    pub containers: Vec<NetworkContainer>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NetworkContainer {
    pub name: String,
    pub ipv4_address: String,
}

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

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