Docker-based agent containerization for the FLUX Fleet — reproducible deployments, isolated execution, standardized tooling.
┌─────────────────────────────────────────────────────────────────┐
│ FLUX FLEET NETWORK │
│ (172.28.0.0/16 — bridge) │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────┐ │
│ │ ORACLE-1 │ │ FLUX RUNTIME │ │
│ │ (coordinator)│ │ FastAPI / Uvicorn :8080 │ │
│ │ 172.28.0.10 │ │ 172.28.0.20 │ │
│ │ CPU: 2.0 │ │ Health: 15s interval │ │
│ │ MEM: 2G │ └──────────────┬───────────────────┘ │
│ └──────┬───────┘ │ │
│ │ │ │
│ depends_on runtime API │
│ │ │ │
│ ┌──────┴───────────────────────────┴──────────────────┐ │
│ │ AGENT LAYER │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │ │
│ │ │ VESSEL-1 │ │ VESSEL-2 │ │ GREENHORN-1 │ │ │
│ │ │ .31 │ │ .32 │ │ .41 │ │ │
│ │ │ 1.5 CPU │ │ 1.5 CPU │ │ 1.0 CPU │ │ │
│ │ │ 1G MEM │ │ 1G MEM │ │ 1G MEM │ │ │
│ │ └──────────┘ └──────────┘ └───────────────┘ │ │
│ │ ┌───────────────┐│ │
│ │ │ GREENHORN-2 ││ │
│ │ │ .42 ││ │
│ │ │ 1.0 CPU ││ │
│ │ │ 1G MEM ││ │
│ │ └───────────────┘│ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ SHARED VOLUMES │ │
│ │ 📁 fleet-data │ 📁 fleet-logs │ 🔐 secrets │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Image Hierarchy:
┌─────────────┐
│ Dockerfile │ ← Python 3.11 + Go 1.21 + Node 20 + Rust
│ .base │
└──────┬──────┘
│
┌────┴─────────────┐
▼ ▼
┌──────────┐ ┌──────────────┐
│Dockerfile│ │ Dockerfile │
│.flux- │ │ .agent │
│ runtime │ │ + git + gh │
└──────────┘ └──────────────┘
Docker 20.10+
Docker Compose v2+
Python 3.11+ (for tests)
GitHub PAT (for agent git operations)
git clone https://github.com/SuperInstance/fleet-containers.git
cd fleet-containers
# Set your GitHub tokenexport GITHUB_TOKEN=" ghp_your_token_here" make logs # Stream all fleet logs# Show running containers# Check health status
Image
Dockerfile
Purpose
Base
fleet/baseDockerfile.baseMulti-language runtime
ubuntu:22.04
fleet/runtimeDockerfile.flux-runtimeFLUX VM execution
python:3.11-slim
fleet/agentDockerfile.agentGeneric agent with git/gh
python:3.11-slim
Python 3.11 — Agent scripting, health checks, testingGo 1.21 — High-performance fleet toolingNode.js 20 — JavaScript/TypeScript agent tasksRust (stable) — Systems-level agent components
Git, GitHub CLI (gh)
Python packages: requests, pyyaml, pytest, docker, gitpython, rich, click, pydantic
Entrypoint with agent bootstrap logic
Common Variables (all containers)
Variable
Default
Description
FLEET_ORGSuperInstanceGitHub organization for fleet repos
LOG_LEVELinfoLogging level (debug, info, warn, error)
GIT_USER_NAMESuper ZGit commit author name
GIT_USER_EMAIL[email protected] Git commit author email
Variable
Default
Description
AGENT_NAMEflux-agentUnique agent identifier
AGENT_ROLEgreenhornAgent role (oracle, vessel, greenhorn)
GITHUB_TOKEN(empty) GitHub PAT for git operations
AGENT_REPOS(empty) Comma-separated list of repos to clone
AGENT_WORKSPACE/home/agent/workspaceAgent working directory
Variable
Default
Description
FLUX_RUNTIME_PORT8080Runtime API port
FLUX_LOG_LEVELinfoRuntime-specific log level
FLUX_VM_HOME/opt/flux-vmVM installation directory
GRACE_PERIOD10Shutdown grace period (seconds)
Target
Description
make helpShow all available targets
make build-allBuild all Docker images
make upStart the full fleet
make downStop the fleet
make restartRestart the fleet
make testRun all tests
make healthCheck container health
make shellShell into running agent
make clean-allRemove containers, images, and volumes
make lintLint Dockerfiles and compose file
The test suite contains 72 tests covering:
Dockerfile validation (T01–T19) — Syntax, instructions, labels, securityCompose validation (T20–T32) — Services, networks, dependencies, resourcesEntrypoint validation (T33–T41) — Git config, auth, agent modes, error handlingHealth check validation (T42–T52) — Script execution, modes, JSON outputNetwork validation (T53–T60) — Driver, IPAM, subnets, labelsMakefile validation (T61–T67) — Build targets, clean, testProject structure (T68–T72) — File existence, no secrets
# Run all teststest
# Run only unit tests# Verbose output🔐 Security Considerations
Never commit GitHub PATs to the repositoryPass tokens via environment variables or Docker secrets
The .gitignore excludes .env files
Tests verify no hardcoded secrets (T72)
Runtime containers run as non-root (flux / agent users)
Each agent has its own container with resource limits
Inter-agent communication only via fleet-internal bridge network
No host port exposure except runtime API (8080)
Bridge network isolates fleet from host network
Static IP assignment prevents address hijacking
DNS resolution is verified by health checks
No privileged mode or capabilities granted
Use slim variants where possible
Pin language versions to prevent supply-chain drift
Layer caching optimized with proper ordering
No build-time secrets in image layers
Base images from official Docker Hub libraries
PPA/deb repos from trusted sources only
rustup verified via TLS (https://sh.rustup.rs)
fleet-containers/
├── Dockerfile.base # Multi-language base image
├── Dockerfile.flux-runtime # FLUX VM runtime container
├── Dockerfile.agent # Generic agent container
├── docker-compose.yml # Multi-agent fleet orchestration
├── fleet-network.yml # Network and volume configuration
├── entrypoint.sh # Agent bootstrap script
├── healthcheck.py # Container health monitoring
├── Makefile # Build, run, test targets
├── README.md # This file
├── scripts/
│ ├── vm-bootstrap.sh # VM initialization
│ └── vm-shutdown.sh # VM graceful shutdown
└── tests/
└── test_containers.py # 72 test cases
FLUX Fleet — SuperInstance
Built with 🚀 by Super Z