Execution agent

Run one EnderCloud agent on every Docker host that may run Minecraft instances. The agent is a small HTTP service with no placement or matchmaking policy. It carries out commands for its own stable host identifier and reports enough information for the orchestrator to reconcile state.

The entry point is orchestrator/src/agent/index.ts. The central and standalone Compose files build it from the same image as the orchestrator but use a different command.

Responsibilities

The agent:

• sends periodic heartbeats with its control URL, game address, resources, and version;
• exposes inventory, inspection, bounded log, create, stop, and delete endpoints;
• downloads missing template layers from the orchestrator;
• verifies the downloaded archive against its expected SHA-256 checksum;
• materializes ordered layers into a disposable instance directory;
• allocates an unused game port from its configured inclusive range;
• pulls missing Docker images and starts resource-constrained containers;
• labels every managed container so reconciliation can prove ownership;
• removes managed containers and their safe runtime directories when requested.

The agent does not query PostgreSQL or Redis. It does not choose a group, variant, session, host, or transfer target.

Start an agent

The primary agent starts with the root stack:

docker compose up --build

For a remote host, copy .env.agent.example to .env.agent, set the private addresses and host paths, then run:

docker compose --env-file .env.agent -f compose.agent.yml up --build -d

To run the agent directly during development:

cd orchestrator
bun install --frozen-lockfile
bun run agent

A direct process still needs Docker access, writable runtime and cache directories, and a reachable orchestrator.

Identity and heartbeat

AGENT_ID is durable identity, not a display name. Do not change it while the host owns managed containers. Docker labels include this value, and the orchestrator uses it for reservations, recovery, and maintenance.

The agent sends one heartbeat immediately after opening its HTTP listener, then repeats at AGENT_HEARTBEAT_INTERVAL. Heartbeats do not overlap. A request times out after the smaller of three seconds and the heartbeat interval.

A successful heartbeat does not immediately make a returning host eligible for placement. The orchestrator first marks it RECOVERING, inventories its containers, resolves missing or orphaned runtime state, then marks it ONLINE.

HTTP API

The agent API is private and unauthenticated.

The orchestrator passes x-request-id and, for durable work, x-command-id. The agent returns the request identifier and includes both values in structured logs.

Template cache

The cache key is <layer-id>/<checksum>. A cache hit requires that exact directory. On a miss, the agent:

1. Requests /api/v1/template-layers/{id}/archive?checksum=<sha256> from the orchestrator.
2. Streams the gzip-compressed tar archive into a unique staging directory.
3. Rejects links, unsupported entry types, absolute paths, and paths that escape staging.
4. Recomputes the canonical layer checksum.
5. Renames staging to the final cache path only after verification succeeds.

Concurrent requests for the same layer and checksum share one download. The current agent does not evict valid cached layers. Monitor or rotate the cache volume on long-lived hosts after old revisions are no longer needed.

Runtime materialization

For a new instance, the agent creates a staging directory under AGENT_RUNTIME_DIRECTORY/instances, copies each ordered layer, removes every variant.yml, then renames staging to the instance identifier. Later layers overwrite earlier files.

The agent passes the host-visible form of the same directory to Docker and mounts it at /data. This is why the local and host runtime paths are separate settings:

• AGENT_RUNTIME_DIRECTORY is the path inside the agent process.
• AGENT_RUNTIME_HOST_DIRECTORY is the path the Docker daemon must bind into a child container.
• AGENT_RUNTIME_LOCAL_DIRECTORY is a Compose host path mounted at AGENT_RUNTIME_DIRECTORY. Compose reads it, not the agent process.

On native Linux, the local and Docker-daemon paths are usually identical. Docker Desktop may expose a Windows directory to its Linux daemon under a path such as /run/desktop/mnt/host/c/EnderCloud/runtime.

Docker behavior

The agent creates containers with:

• name endercloud-<variant-id>-<instance-id>;
• memory and CPU limits from the resolved variant;
• /data bound to the materialized runtime directory;
• container port 25565 published on the first free configured host port;
• the configured local Docker network;
• ownership labels for host, instance, group, variant, session, and host port;
• ENDERCLOUD_INSTANCE_ID and ENDERCLOUD_ORCHESTRATOR_URL injected into the container.

Create is safe to retry for the same instance identifier. If a correctly labelled container already exists, the agent starts it if needed and returns its existing endpoint. Port selection and container creation use a per-agent lock so concurrent creates cannot reserve the same port.

Cleanup lists only containers carrying orchestrator.managed=true and the current agent's host label. Orphan deletion checks the labels again immediately before removal. Runtime deletion also refuses any path that is not one direct child of the configured instances directory.

Environment variables

This table lists every variable read by the agent process. Defaults come from orchestrator/src/agent/config.ts.

Durations require an integer and one of ms, s, m, h, or d.

The Docker socket default depends on the operating system of the agent process. The supplied Compose files run the agent in a Linux container and mount /var/run/docker.sock explicitly.

Compose-only variables

These variables configure host mounts and published ports. The agent process does not read them.

The local two-agent smoke test also consumes these scenario-only values:

Managed-container variables

The agent injects these values into every managed Minecraft container after applying the variant environment:

A template may set ENDERCLOUD_REPORTED_ENDPOINT to make the Paper bridge report a different endpoint in SERVER_READY. Most deployments should use the endpoint allocated by the agent and leave this unset.

Velocity is not a managed Minecraft container. Its plugin separately reads ENDERCLOUD_ORCHESTRATOR_URL and ENDERCLOUD_REDIS_URL, both defaulting to localhost values when unset.

Security and operations

Never publish the agent control API or Docker socket to an untrusted network. A caller that can reach the agent API can create and remove managed workloads. Bind AGENT_PUBLISH_ADDRESS to a private interface and restrict inbound traffic to the orchestrator.

The game-port range is the only agent-owned port range intended for player traffic. Make it large enough for the host's maximum simultaneous instances and ensure it does not overlap another agent sharing the same Docker daemon.

See Multi-host execution for routing, maintenance, and recovery procedures.