[GH-ISSUE #59] Multi-node deployment without Kubernetes #26

New issue

Closed

opened 2026-10-29 14:18:31 +00:00 by bsakaguchi · 2 comments

bsakaguchi commented

2026-10-29 14:18:31 +00:00

Owner

Originally created by @herethere on GitHub (Jul 29, 2026).
Original GitHub issue: https://github.com/kvcache-ai/AgentENV/issues/59

Hi, I'm planning to deploy AgentENV across ~10 physical machines for agentic RL training.

The documentation covers two multi-node paths:

Docker Compose — described as "Multi-Node Simulation" (single host only)
Kubernetes / k3s — the only documented true multi-machine option

My question: is there a supported way to run a real multi-node cluster without Kubernetes?

Specifically, I'm wondering if the following approach would work:

Run aenv-node via the install script + systemd on each physical machine
Run Gateway and Scheduler as standalone processes (or Docker containers) on a control machine
Configure each node to report heartbeats to the Scheduler via AENV_OBSERVABILITY_SCHEDULER_ENDPOINT

Or is Kubernetes/k3s currently the only supported path for multi-machine deployments?

Thanks!

Originally created by @herethere on GitHub (Jul 29, 2026). Original GitHub issue: https://github.com/kvcache-ai/AgentENV/issues/59 Hi, I'm planning to deploy AgentENV across ~10 physical machines for agentic RL training. The documentation covers two multi-node paths: - **Docker Compose** — described as "Multi-Node Simulation" (single host only) - **Kubernetes / k3s** — the only documented true multi-machine option My question: is there a supported way to run a real multi-node cluster **without Kubernetes**? Specifically, I'm wondering if the following approach would work: - Run `aenv-node` via the install script + systemd on each physical machine - Run Gateway and Scheduler as standalone processes (or Docker containers) on a control machine - Configure each node to report heartbeats to the Scheduler via `AENV_OBSERVABILITY_SCHEDULER_ENDPOINT` Or is Kubernetes/k3s currently the only supported path for multi-machine deployments? Thanks!

bsakaguchi closed this issue

2026-10-29 14:18:31 +00:00

bsakaguchi commented

2026-10-29 14:18:32 +00:00

Author

Owner

@yingdi-shan commented on GitHub (Jul 29, 2026):

Yes, a non-Kubernetes cluster can be started with static node discovery:

Compile the Scheduler and Gateway from the repository root:

make -C services build

Edit deploy/docker/config/default.json. Add each AgentENV node to scheduler.nodes using its node ID and reachable IP/port:

"nodes": [
  {
    "id": "node-a",
    "endpoint": "http://<ip-node-a>:8000"
  },
  {
    "id": "node-b",
    "endpoint": "http://<ip-node-b>:8000"
  }
]

Also set gateway.scheduler_addr to the Scheduler address:

"scheduler_addr": "<ip-scheduler>:9090"

Start the Scheduler:

scheduler -config deploy/docker/config/default.json

It's recommended to create a systemd service to manage scheduler.

On each AgentENV node, set its node ID and Scheduler endpoint in /etc/default/aenv:

API_ADDR="0.0.0.0:8000"
AENV_NODE_ID="node-a"
AENV_OBSERVABILITY_SCHEDULER_REPORT_ENABLED="true"
AENV_OBSERVABILITY_SCHEDULER_ENDPOINT="http://10.0.0.10:9090"

Then start the node:

sudo systemctl start aenv

The AENV_NODE_ID must match the corresponding entry in scheduler.nodes.

Start the Gateway with the same JSON configuration:

gateway -config deploy/docker/config/default.json

Without Kubernetes, automatic node discovery is not currently supported. Heartbeats do not register unknown nodes, so every node must be listed explicitly in scheduler.nodes. Changes to the static node list require restarting the Scheduler.

We would welcome a PR adding this non-Kubernetes multi-node setup to the deployment documentation.

@yingdi-shan commented on GitHub (Jul 29, 2026): Yes, a non-Kubernetes cluster can be started with static node discovery: 1. Compile the Scheduler and Gateway from the repository root: ```bash make -C services build ``` 2. Edit `deploy/docker/config/default.json`. Add each AgentENV node to `scheduler.nodes` using its node ID and reachable IP/port: ```json "nodes": [ { "id": "node-a", "endpoint": "http://<ip-node-a>:8000" }, { "id": "node-b", "endpoint": "http://<ip-node-b>:8000" } ] ``` Also set `gateway.scheduler_addr` to the Scheduler address: ```json "scheduler_addr": "<ip-scheduler>:9090" ``` 3. Start the Scheduler: ```bash scheduler -config deploy/docker/config/default.json ``` It's recommended to create a systemd service to manage scheduler. 4. On each AgentENV node, set its node ID and Scheduler endpoint in `/etc/default/aenv`: ```bash API_ADDR="0.0.0.0:8000" AENV_NODE_ID="node-a" AENV_OBSERVABILITY_SCHEDULER_REPORT_ENABLED="true" AENV_OBSERVABILITY_SCHEDULER_ENDPOINT="http://10.0.0.10:9090" ``` Then start the node: ```bash sudo systemctl start aenv ``` The `AENV_NODE_ID` must match the corresponding entry in `scheduler.nodes`. 5. Start the Gateway with the same JSON configuration: ```bash gateway -config deploy/docker/config/default.json ``` Without Kubernetes, automatic node discovery is not currently supported. Heartbeats do not register unknown nodes, so every node must be listed explicitly in `scheduler.nodes`. Changes to the static node list require restarting the Scheduler. We would welcome a PR adding this non-Kubernetes multi-node setup to the deployment documentation.

bsakaguchi commented

2026-10-29 14:18:33 +00:00

Author

Owner

@catyans commented on GitHub (Jul 31, 2026):

I can take the documentation PR described here. I will document a real multi-machine static-discovery deployment (Scheduler, Gateway, systemd-managed AgentENV nodes), explicitly call out that heartbeats do not auto-register nodes, and include configuration/verification/troubleshooting steps based on the current config and binaries.

@catyans commented on GitHub (Jul 31, 2026): I can take the documentation PR described here. I will document a real multi-machine static-discovery deployment (Scheduler, Gateway, systemd-managed AgentENV nodes), explicitly call out that heartbeats do not auto-register nodes, and include configuration/verification/troubleshooting steps based on the current config and binaries.

bsakaguchi referenced this issue

2026-10-29 14:19:34 +00:00

[GH-ISSUE #390] feature(qemu-backend): add a QEMU sandbox backend for GPU, Windows and macOS sandboxes #99