Crate clawbox_containers 

clawbox-containers

Docker container lifecycle management for clawbox agent sandboxing.

Overview

clawbox-containers manages the full lifecycle of Docker containers used as agent sandboxes. It handles container creation with security hardening, workspace isolation, per-container authentication, agent-level orchestration, and automatic cleanup of orphaned containers. This crate is used by clawbox-server to provide the Container and ContainerDirect sandbox policies.

Usage

use clawbox_containers::{DockerBackend, ContainerBackend, AgentOrchestrator};
use clawbox_types::ContainerSpawnRequest;
use std::sync::Arc;
use std::path::PathBuf;

// Create a Docker backend (requires Docker daemon)
let backend = DockerBackend::new().await?;

// Spawn a sandboxed container via the ContainerBackend trait
use clawbox_types::Capabilities;
let request = ContainerSpawnRequest::new("Run code analysis", Capabilities::default())
    .with_image("alpine:latest");
let container_info = backend.spawn(request, 18080, None).await?;

// Or use the AgentOrchestrator for agent-level lifecycle management
let orchestrator = AgentOrchestrator::new(
    Arc::new(backend) as Arc<dyn ContainerBackend>,
    PathBuf::from("/tmp/workspaces"),
);

Features

• Container lifecycle — Create, start, monitor, stop, and remove containers with timeout enforcement
• Security hardening — Read-only root filesystem, dropped capabilities, no-new-privileges flag, seccomp profiles
• Image allowlisting — Only pre-approved image prefixes can be used (ghcr.io/n0xmare/, alpine:, ubuntu:, debian:)
• Workspace isolation — Per-agent host directories mounted into containers with configurable read-only mode
• Per-container auth — Each container receives a unique bearer token for proxy authentication
• Agent orchestration — Register, start, stop, and track agents with idle timeouts and crash recovery
• Orphan reaper — Background task scans for containers with clawbox labels not tracked by the manager, stops and removes them
• Graceful shutdown — Containers are stopped cleanly on server shutdown

Architecture

Module	Purpose
manager	Core container lifecycle (spawn, stop, remove, list) via DockerBackend
orchestrator	Agent-level state management over containers
lifecycle	Background monitoring for timeouts and status transitions
reaper	Periodic cleanup of orphaned Docker containers
config	Security settings, defaults, and image allowlists
auth	Per-container bearer token generation and validation
backend	ContainerBackend trait for abstracting container runtimes

Safety / Security

• Requires Docker daemon — The Docker socket must be accessible
• Least privilege — Containers run with dropped capabilities, read-only rootfs, and no-new-privileges
• Image allowlisting — Prevents spawning arbitrary images; only approved prefixes are accepted
• Isolation — Each container gets its own network namespace, workspace mount, and auth token
• Reaper — Prevents resource leaks by cleaning up containers that outlive their manager

License

MIT

Re-exports

pub use backend::ContainerBackend;

pub use error::ContainerError;

pub use error::ContainerResult;

pub use manager::DockerBackend;

pub use orchestrator::AgentOrchestrator;

Modules

auth

Per-container authentication tokens.

backend

Backend trait for container operations.

config

Container configuration — security settings and defaults.

error

Error types for container management operations.

lifecycle

Container lifecycle management — timeout monitoring and status updates.

manager

Container manager — coordinates Docker container lifecycle.

orchestrator

Agent-level orchestration over containers.

reaper

Periodic reaper for orphaned clawbox containers.