Docker Compose (Multi-Node Simulation)

Run a full multi-node stack on a single host using Docker Compose. This simulates a production-like topology with a gateway, scheduler, and multiple AgentENV backend nodes.

What Gets Started

Prerequisites

• Linux kernel 6.8+
• /dev/kvm access (passed into the runtime containers)
• Docker and Docker Compose
• build-essential (sudo apt install -y build-essential)

Clone the Repository

git clone https://github.com/kvcache-ai/AgentENV.git
cd AgentENV

Start the Cluster

sudo bash scripts/docker-setup.sh
make deploy-up

To enable host-based sandbox data-plane URLs, set the shared sandbox proxy domain variable when starting the stack:

SANDBOX_PROXY_DOMAINS=sandbox.example.com \
make deploy-up

Compose passes this value to both the gateway routing allowlist and runtime nodes’ sandbox response metadata. The domain must resolve to the gateway, usually through wildcard DNS for *.sandbox.example.com.

Verify

# Health check via gateway
curl http://127.0.0.1:8080/health

# Cluster node snapshots via gateway
curl http://127.0.0.1:8080/nodes

# Direct health check on a backend node
curl http://127.0.0.1:8001/health

Management Commands

make deploy-ps      # Show container status
make deploy-logs    # Stream logs from all services
make deploy-down    # Tear down the cluster

Configuration

Container deployments use deploy/docker/config/default.json. Scheduler and backend node endpoints are configured for the Docker network.

The runtime image includes uvm-ublk at /usr/local/bin/uvm-ublk. Compose uses that path instead of a host-built env/ublk/uvm-ublk binary.

The compose manifest also wires node heartbeat reporting from runtime nodes to scheduler:

• AENV_NODE_ID is set explicitly per node container (node-a, node-b).
• AENV_OBSERVABILITY_SCHEDULER_REPORT_ENABLED=true enables scheduler heartbeat reporting.
• AENV_OBSERVABILITY_SCHEDULER_ENDPOINT is set to http://scheduler:9090.
• SANDBOX_PROXY_DOMAINS, when set, is passed through as both GATEWAY_SANDBOX_PROXY_DOMAINS and AENV_SANDBOX_PROXY_DOMAINS.