A Deep Dive into the Minimal Docker “Chassis” for Long‑Running Agent Fleets

(≈4,200 words)

1. Introduction

The modern software ecosystem is increasingly driven by continuous integration / continuous delivery (CI/CD) pipelines, monitoring and observability stacks, and security tooling that must run thousands of lightweight agents across distributed environments. While traditional orchestration platforms like Kubernetes or Docker Swarm provide robust solutions for containerized workloads, they often introduce significant operational overhead—complex installation, steep learning curves, and unnecessary resource consumption—especially when the use case is limited to running long‑running, long‑lived agents that perform periodic or streaming tasks.

Enter “chassis”, a minimal, bare‑bones agent orchestration layer built around Docker and a simple two‑layer file system. The concept is elegant: leverage Docker’s well‑understood container runtime to encapsulate an agent, while providing just enough orchestration glue to manage, scale, and monitor a fleet of such agents. In this article, we’ll walk through chassis’s design, implementation, use cases, and how it compares to the more heavyweight orchestration solutions that dominate the market today.

TL;DR – Chassis is a lightweight Docker‑based orchestrator designed to run long‑running agent fleets with minimal overhead, providing a simple file system abstraction, easy deployment, and basic health‑checking without the complexity of Kubernetes or Docker Swarm.

2. Why a Minimal Agent Orchestrator is Needed

2.1 The Problem Space

When organizations adopt micro‑services or distributed architectures, they frequently need to run a large number of agents—for example:

• Monitoring agents that collect metrics and logs from servers.
• Security agents that perform vulnerability scans or endpoint protection.
• Data pipeline agents that ingest and forward telemetry to cloud platforms.
• Build agents that execute CI jobs on a fleet of machines.

These agents are typically:

• Long‑lived: They run for days or weeks, often without redeployment.
• Stateful to some degree: They may maintain local caches, buffers, or logs.
• Distributed: They may be deployed across multiple hosts, regions, or environments.
• Resource‑constrained: They usually consume only a few megabytes of memory and CPU.

Given these characteristics, the agents do not require the full feature set of a cluster manager like Kubernetes. They also often suffer from resource waste or security complexity when bundled into a larger platform that was designed for stateless micro‑services.

2.2 Existing Solutions and Their Drawbacks

| Platform | Key Features | Typical Use‑Case | Drawbacks for Agent Fleets | |----------|--------------|------------------|---------------------------| | Kubernetes | Auto‑scaling, rolling updates, multi‑cluster support | Deploy micro‑services, batch jobs, AI workloads | Requires ~100 MiB per node, complex kube‑config, steep learning curve | | Docker Swarm | Simpler setup than Kubernetes, built‑in load balancing | Small to medium clusters | Still requires orchestrator process, not ideal for long‑lived jobs | | HashiCorp Nomad | Lightweight job scheduler, HCL config | Edge, CI pipelines | Requires extra components for networking, not focused on agent lifecycle | | Docker Compose | Multi‑container local development | Simple development stacks | No production‑grade scaling or health‑checks | | Custom Scripts | Bash or Python scripts using Docker API | Ad‑hoc agent management | Hard to maintain, brittle, lacks observability |

Bottom line: For an environment that demands high density (hundreds of agents) but low complexity, the existing orchestrators either over‑provide features or under‑deliver on the required agent‑centric controls. The “chassis” project fills that niche.

3. Chassis Overview

Chassis is “bare‑bones” in the sense that it implements only the essential pieces of an orchestrator:

1. Container Lifecycle Management – Start, stop, restart, and monitor Docker containers that encapsulate agents.
2. File System Abstraction – Two‑layer user‑agent‑native file system that isolates agent data and state.
3. Health Monitoring – Basic readiness and liveness checks that expose agent status.
4. CLI & REST API – Simple command‑line interface and a minimal HTTP API for automation.

Under the hood, chassis relies on the Docker Engine API. It does not embed any of the heavy machinery from Kubernetes or Swarm; instead, it delegates the heavy lifting of container scheduling, networking, and storage to Docker itself. This means chassis can be deployed on any host that runs Docker, whether it’s a dedicated server, a cloud VM, or a small edge device.

Key Design PrinciplesMinimalism: Only features that are necessary for agent lifecycle.Simplicity: Single binary, zero configuration files.Extensibility: Plugin hooks for custom agents.Security: Minimal attack surface, runs as non‑root when possible.

4. Architecture Deep Dive

4.1 The Two‑Layer File System

At the heart of chassis is a two‑layer file system that serves two purposes:

1. System Layer – Contains the core chassis runtime, shared libraries, and configuration.
2. Agent‑Native Layer – A per‑agent namespace that isolates all agent data.

This design has several benefits:

• Isolation: Each agent cannot read/write to other agents’ data, improving security.
• Persistence: Agent state is persisted in Docker volumes, ensuring data survives container restarts.
• Portability: The agent’s file system can be exported and imported, simplifying migrations.

4.1.1 How the Layers are Implemented

• The system layer lives in a dedicated Docker volume (chassis_system).
• Each agent gets a volume mount (chassis_agent_<ID>) that is mounted at /agent_data inside the container.
• The container's working directory is set to /agent_data so the agent’s native file operations are automatically redirected to its isolated space.

This separation eliminates the need for complex bind‑mount logic and ensures that the container runtime is fully aware of the agent’s file system boundaries.

4.2 Container Lifecycle Manager

Chassis uses the Docker SDK for Go (or the REST API via curl in simpler deployments) to issue commands to the Docker daemon:

• Create: Pulls the agent image from a registry, sets environment variables, mounts volumes, and assigns network settings.
• Start: Starts the container with appropriate --restart=unless-stopped policy.
• Stop: Gracefully stops the container, sending a SIGTERM, waiting for a configurable grace period, then SIGKILL if necessary.
• Restart: Combines stop + start with optional pre‑restart hooks.

Because chassis doesn’t manage scheduling, all agents are run on the same host or distributed manually across hosts that each run a local chassis instance. For distributed deployments, chassis can expose a simple REST API that other chassis instances poll to coordinate workloads.

4.3 Health Monitoring

Health checks are vital for long‑running agents. Chassis implements:

• Readiness Probe: Checks if the agent container’s main process is up and listening (e.g., via a TCP health‑check).
• Liveness Probe: Periodically pings the agent’s health endpoint (if available) or checks process existence.
• Metrics Endpoint: Exposes a simple /metrics endpoint that returns JSON with uptime, memory usage, and custom agent metrics (if the agent writes them to /agent_data/metrics.json).

The health checks run inside chassis itself, independent of the agent’s own health logic, providing an extra layer of confidence.

4.4 CLI & REST API

4.4.1 Command‑Line Interface

Chassis ships with a single binary, chassis, that exposes subcommands:

chassis deploy <agent_image> --id <agent_id>
chassis stop <agent_id>
chassis status <agent_id>
chassis list

Each command prints JSON‑formatted output for easy consumption by CI pipelines or monitoring tools.

4.4.2 REST API

For automation, chassis exposes a minimal HTTP API:

| Endpoint | Method | Description | |----------|--------|-------------| | /agents | GET | List all running agents with status. | | /agents/<id> | GET | Get detailed status for a specific agent. | | /agents/<id>/start | POST | Start the agent. | | /agents/<id>/stop | POST | Stop the agent. | | /agents/<id>/restart | POST | Restart the agent. | | /metrics | GET | Global metrics across all agents. |

The API is intentionally simple, focusing on CRUD operations and status queries. Authentication can be added via environment variables (CHASSIS_API_TOKEN) or integrated into a reverse proxy (e.g., Nginx) for production deployments.

5. Implementation Details

5.1 Language & Dependencies

• Go is the primary language for chassis, chosen for its static binaries, fast startup, and robust Docker SDK.
• The project is structured as a single repository with a cmd/chassis package for the binary, a pkg/ directory for reusable modules (e.g., Docker client wrapper, file system abstraction, health checks), and api/ for the HTTP handlers.
• Dependencies:
• github.com/docker/docker/client – Docker SDK.
• github.com/gin-gonic/gin – lightweight HTTP router.
• github.com/spf13/cobra – CLI command framework.

The compiled binary is ≈5 MB and can be executed on most Linux distributions, including Alpine.

5.2 Docker Volume Management

Chassis automatically creates Docker volumes:

• chassis_system – Stores shared config and metadata.
• chassis_agent_<ID> – Dedicated per‑agent volume.

Volumes are created lazily when an agent is first deployed. If an agent is removed, the associated volume can be cleaned up using chassis delete <id> --purge. This prevents orphaned data and keeps the host storage tidy.

5.3 Agent Configuration Injection

When deploying an agent, chassis allows injection of environment variables or configuration files via flags:

chassis deploy myorg/agent:v1.2.3 \
    --id agent42 \
    --env NODE_ID=42 \
    --config /path/to/config.yaml

The --config flag mounts a local file into the agent’s data directory (/agent_data/config.yaml). This mechanism is ideal for agents that read local config files instead of environment variables.

5.4 Logging Strategy

Each agent’s stdout/stderr is automatically forwarded to Docker’s logging driver (json-file). Chassis also aggregates logs via a background goroutine that tails the Docker logs and writes them to a central file (/var/log/chassis/agent_<ID>.log). For environments requiring structured logs, chassis can forward logs to a Logstash/ELK stack via a sidecar container or a log forwarder plugin.

6. Use Cases & Real‑World Scenarios

6.1 Continuous Integration Agents

In a CI environment, build agents often need to run for hours or days, fetching code, compiling, and reporting results. Chassis can manage dozens of build agents on a single host, ensuring they stay up and have isolated work directories. CI pipelines can trigger chassis via the REST API to start agents on demand, reducing idle resource usage.

6.2 Security Monitoring

Endpoint security tools like Sysdig Falco, OSSEC, or custom lightweight scanners can be packaged as agents. Chassis can run them as long‑running containers, collect logs, and push results to a central SIEM. The minimal file system ensures that sensitive audit logs remain isolated per agent.

6.3 Telemetry Collection

Edge devices that send telemetry (e.g., IoT gateways) can host chassis to run multiple agents that read sensors and forward data to the cloud. The low overhead of chassis is perfect for low‑power devices where every megabyte of RAM counts.

6.4 Data Ingestion Pipelines

Agents that consume Kafka topics, perform transformations, and push to downstream systems (e.g., Elasticsearch, BigQuery) can be orchestrated by chassis. Since these agents are long‑running and often require local state (e.g., checkpoint files), chassis’s volume abstraction preserves state across restarts.

7. Benefits Over Traditional Orchestrators

| Feature | Chassis | Kubernetes | Docker Swarm | Nomad | |---------|---------|------------|--------------|-------| | Deployment Size | 5 MB binary | ~1 GB (kube‑apiserver, etc.) | ~300 MB | ~200 MB | | Setup Complexity | One binary + Docker | Helm charts, kube‑config | docker swarm init | nomad agent | | Resource Footprint | <10 MiB RAM per chassis | 250 MiB+ per node | 50 MiB+ | 30 MiB+ | | Scalability | Horizontal scaling via multiple chassis instances | Unlimited | Unlimited | Unlimited | | Agent Isolation | Per‑agent volume + Docker | Namespace + PVC | Namespace | Namespace | | Health Checks | Built‑in liveness/readiness | Liveness/Readiness probes | Readiness only | Health checks | | Network Overhead | Docker network | CNI plugins | Overlay network | CNI plugins | | Observability | JSON metrics + logs | Prometheus + Grafana | Prometheus + Grafana | Prometheus + Grafana | | Security | Minimal attack surface | RBAC + pod‑security | Service mesh optional | ACLs + TLS |

Key Takeaways

• Smaller Footprint: Chassis is ideal for resource‑constrained hosts or edge deployments.
• Simplicity: One binary, no cluster initialization, minimal configuration.
• Granular Control: Agents are isolated at the file system level, preventing accidental data leaks.
• Fast Start‑up: Docker’s container creation is sub‑second, allowing rapid scaling of agents.

8. Limitations & Trade‑Offs

No solution is perfect, and chassis’s minimalism comes with a few caveats:

1. Limited Scheduling – Chassis does not perform sophisticated scheduling across hosts. If you need to balance load or avoid over‑committing resources, you must orchestrate chassis instances manually or use a lightweight scheduler like HashiCorp Nomad in tandem.
2. No Built‑in Multi‑Host Networking – While Docker can run on a host‑mode network, chassis does not expose a native service mesh or overlay network. For cross‑host communication, you’ll need to rely on external networking solutions (e.g., Traefik, Envoy).
3. Scaling to Thousands of Agents – While chassis can manage dozens of agents per host efficiently, scaling to thousands on a single host may strain Docker’s resources or exceed the host’s CPU/memory limits.
4. No GUI – Chassis intentionally eschews a web UI to keep the binary lean. Monitoring and management must be done via CLI or the REST API.
5. Extensibility Requires Custom Development – Although chassis provides hooks, adding advanced features (e.g., auto‑healing, self‑service deployment) will require writing custom code or integrating with third‑party tools.

Despite these trade‑offs, chassis shines in scenarios where simplicity, speed, and low overhead outweigh the need for advanced orchestration features.

9. Future Roadmap

The chassis team has outlined several enhancements slated for upcoming releases:

1. Cluster Coordination – A lightweight leader election mechanism to coordinate agent deployments across multiple chassis instances.
2. Service Mesh Integration – Optional sidecar injection to provide mTLS and traffic routing between agents.
3. Dynamic Scaling Policies – Automatic scaling based on agent metrics (CPU, memory, queue depth).
4. Improved Security – Rootless operation mode, integration with Docker’s user‑namespaces.
5. Unified UI – A lightweight web dashboard built with Vue.js that consumes the REST API.
6. Plugin System – Allow developers to plug in custom health‑check logic, log forwarders, or storage backends.

The open‑source nature of chassis means contributors can jump in to implement any of these features, or propose new ideas via GitHub issues.

10. Getting Started – A Step‑by‑Step Guide

Below is a quick‑start guide to run chassis on a fresh Ubuntu 24.04 LTS host.

10.1 Prerequisites

• Docker Engine (≥20.10) installed and running.
• Go (≥1.20) if you want to build from source.

sudo apt update && sudo apt install -y docker.io golang
sudo systemctl enable --now docker

10.2 Build the Chassis Binary

git clone https://github.com/myorg/chassis.git
cd chassis
go build -o chassis ./cmd/chassis
sudo mv chassis /usr/local/bin/

10.3 Deploy an Agent

Assume we have an agent image myorg/hello-agent:v1. This agent simply prints “Hello, World!” and exits.

chassis deploy myorg/hello-agent:v1 \
    --id hello1 \
    --env GREETING="Hello, World!" \
    --config ./config.yaml

Chassis will:

1. Pull myorg/hello-agent:v1.
2. Create a Docker volume chassis_agent_hello1.
3. Mount the volume at /agent_data.
4. Start the container with environment variables and config.

10.4 Check Status

chassis status hello1

Output:

{
  "id": "hello1",
  "image": "myorg/hello-agent:v1",
  "status": "running",
  "uptime": "42s",
  "cpu": "0.5%",
  "memory": "12MiB"
}

10.5 Stop & Remove

chassis stop hello1
chassis delete hello1 --purge

The --purge flag removes the associated Docker volume, ensuring no leftover data.

10.6 Use the REST API

curl http://localhost:8080/agents/hello1/status

Will return the JSON status similar to the CLI.

11. Comparative Case Study: Chassis vs. Kubernetes

To illustrate chassis’s strengths, let’s compare deploying a 100‑agent telemetry collector on both chassis and Kubernetes.

11.1 Kubernetes Setup

• Helm chart for the agent image.
• Deployment with 100 replicas, each agent in a separate pod.
• PersistentVolumeClaims for each agent.
• Service to expose each pod’s metrics.
• HorizontalPodAutoscaler for auto‑scaling.

Resources: ~1 GB RAM + 200 MiB CPU for the control plane; ~50 MiB per agent.

Operational Overhead: Need to manage kube‑config, RBAC rules, namespace policies, and monitoring dashboards.

11.2 Chassis Setup

• One chassis binary per host.
• Deploy all 100 agents via chassis deploy commands, or via a simple shell script.
• Each agent gets its own Docker volume.
• Health checks via chassis.

Resources: ~5 MB binary + 5 MiB RAM; ~12 MiB per agent (including volume).

Operational Overhead: Minimal. No cluster management, no separate monitoring stack (unless you choose to add one).

11.3 Results

| Metric | Kubernetes | Chassis | |--------|------------|---------| | Initial Setup Time | 30 min (including kube‑config) | <5 min | | Memory Footprint | 1.2 GB | 200 MiB | | Agent Isolation | Namespaces, PVCs | Volumes | | Scaling Speed | 10 min to 100 replicas | <1 min | | Observability | Prometheus + Grafana | JSON metrics + custom dashboards | | Security Complexity | RBAC, pod‑security | None (Docker defaults) |

Conclusion – For this scenario, chassis is 6× lighter in resource usage and 5× faster to deploy, making it ideal for environments where the cluster manager’s overhead is prohibitive.

12. Security Considerations

When deploying long‑running agents, security is paramount. Here are key practices when using chassis:

1. Run as Non‑Root – Docker containers should run as a dedicated non‑root user. In the agent image, set USER agent and adjust file permissions accordingly.
2. Use Docker’s User‑Namespaces – Enable user‑namespaces in Docker to map the container’s root to a non‑privileged user on the host.
3. Restrict Network – Use Docker’s network modes (host, bridge, none) to control inbound/outbound traffic. For isolated agents, none can be used to block external networking.
4. Audit Logs – Enable Docker audit logs (/etc/docker/daemon.json with "audit-logging": true) to track container start/stop events.
5. TLS for REST API – When exposing the chassis REST API publicly, use TLS certificates and API token authentication.
6. Least Privilege Volumes – Mount volumes with ro (read‑only) where possible, and avoid binding host directories into containers.

13. Integrating Chassis into CI/CD Pipelines

Many teams want agents to run as part of a pipeline job. Here’s how chassis can be integrated:

# .gitlab-ci.yml
build-job:
  image: docker:stable
  services:
    - docker:dind
  script:
    - docker pull myorg/agent:v2
    - chassis deploy myorg/agent:v2 --id build-${CI_PIPELINE_ID}
    - # Run some tests inside the agent container
    - docker exec build-${CI_PIPELINE_ID} sh -c "run-tests"
    - chassis stop build-${CI_PIPELINE_ID}
    - chassis delete build-${CI_PIPELINE_ID} --purge

The pipeline leverages Docker in Docker to pull the agent image and control chassis. This pattern ensures that each pipeline run has its own isolated agent instance, reducing interference between jobs.

14. Community & Ecosystem

Chassis is open‑source under the Apache 2.0 license. The project hosts:

• GitHub Repository – Source code, issue tracker, pull requests.
• Docker Hub – Official chassis image (myorg/chassis:latest).
• Slack Channel – #chassis-dev for real‑time support.
• Contributing Guide – Instructions for building, testing, and submitting PRs.

The ecosystem includes community‑built agent images (e.g., security scanners, log collectors) that are ready to be deployed via chassis. A curated list of these images is maintained in the AGENTS.md file in the repo.

15. Key Takeaways

1. Minimalism Wins – When you need to run thousands of long‑running agents, a full Kubernetes cluster is overkill.
2. Docker Is Enough – Docker provides a mature, battle‑tested runtime; chassis builds on top of it.
3. File System Isolation – Two‑layer volume design ensures agents are sandboxed and persistent.
4. Fast Deployment – CLI and REST API make it easy to programmatically deploy agents.
5. Scalable – By running multiple chassis instances across hosts, you can scale to large fleets without the complexity of cluster management.

16. Closing Thoughts

The “chassis” project represents a pragmatic response to a real pain point in modern DevOps: managing agent fleets efficiently and securely without the weight of a full orchestration platform. Its core strengths—minimal resource footprint, simple deployment, and robust isolation—make it an attractive option for small to medium enterprises, edge deployments, and any environment where agility trumps scale.

As the world of distributed systems continues to evolve, tools like chassis remind us that sometimes the best solution is the simplest. If your organization relies heavily on long‑running agents, consider giving chassis a try. The lightweight nature of the tool means you can experiment without committing to a full Kubernetes investment, and the open‑source community ensures that you’re not locked into a proprietary stack.

Happy orchestrating! 🚀