@ai-development-environment/control-agent

Control agent for the AI Development Environment. It makes authenticated outbound HTTP and GraphQL WebSocket connections to the control plane; managed machines do not expose a listening port.

Install

npm install -g @ai-development-environment/control-agent

Requires Node.js 24 (>=24.16.0 <25). Saved commands use the agent user's login shell and require no additional runtime.

Usage

Open the server's Agents page and create a one-time enrollment command, then run it on the target machine (the server defaults to the same computer when omitted):

control-agent enroll \
  --server http://127.0.0.1:3090 \
  --enrollment-token <one-time-token>
control-agent run

Local and remote endpoints

One control plane is often reachable at two addresses — a LAN address at the desk and a public or VPN address elsewhere. Configure both and the agent prefers the local one, moving to the remote one when the local address stops answering and the remote one is confirmed to be answering. A control plane that is down at every configured address is not a failover: the agent keeps its session and the jobs running under it, and reconnects when the server comes back.

control-agent enroll \
  --server http://192.168.1.10:3090 \
  --remote-server https://control.example.com \
  --enrollment-token <one-time-token>

Change the addresses on an enrolled agent, or print the current ones by passing no flags:

control-agent endpoints
control-agent endpoints --remote-server https://control.example.com
control-agent endpoints --clear-remote

The websocket address of each endpoint is derived from its server URL unless --websocket-server or --remote-websocket-server sets it explicitly.

Changing a server address re-derives its websocket address, because one stored against the old server no longer points anywhere useful. If the websocket is served from somewhere other than /graphql on the same host and port — behind a reverse proxy, say — pass it alongside the new server address:

control-agent endpoints --server http://192.168.1.20:3090 --websocket-server ws://192.168.1.20:3092/graphql

Enrollment

control-agent enrollment
control-agent unenroll

enrollment reports whether this machine is enrolled and whether each configured endpoint answers for it. unenroll removes the local credential; the control plane still lists the agent until it is deleted there.

Diagnostics:

control-agent status
control-agent doctor

The credential and stable agent ID are stored at ~/.config/control-agent/config.json.

See also

• @ai-development-environment/server — the control-plane server.
• The Homebrew tap — alternative install that runs the agent as a brew services daemon.