Nodes & the daemon
A node is a remote Linux machine that runs agent sessions. It runs the Halyard daemon, a lightweight worker process — bring your own laptop, server, or VM.
The daemon connection model
Section titled “The daemon connection model”The daemon keeps a single persistent outbound WebSocket to the control plane. Crucially, there is no inbound listener on the node and no broker in the middle — every frame flows over that one connection. This is what lets nodes run behind NAT or a firewall without opening ports.
Over that connection the daemon:
- registers the node and advertises its capacity and hardware profile;
- heartbeats continuously so the control plane tracks health;
- receives dispatches and streams live terminal output back.
Scheduling and offline resilience
Section titled “Scheduling and offline resilience”When you dispatch a session, the control plane places it on an online node in the project’s enclave that has capacity. If no node is available, the session stays queued in durable storage and is dispatched the moment a node reconnects and reports capacity — you get durable-queue behavior without operating a queue.
If a node stops heartbeating past the timeout, it’s marked offline and any sessions assigned to it are unstuck and re-queued.
Execution environments
Section titled “Execution environments”Each session picks how its workspace is provisioned on the node:
- Host directory — the agent works directly in an existing directory, reusing installed toolchains and build caches. Best when setup is expensive or already done.
- Containerized — the daemon builds an ephemeral environment from a Dockerfile or Docker Compose, mounts the cloned repo, and tears it down when the session ends. Best for clean, reproducible isolation.
Preview tunnels
Section titled “Preview tunnels”To view a dev server running inside a workspace, Halyard can open an ephemeral
preview tunnel bound to a (workspace, port) pair and relay it to your
browser — again without the node ever opening an inbound port. Tunnels track
their own lifecycle and are swept when idle.
Managing nodes
Section titled “Managing nodes”Register, monitor, and retire nodes under Nodes in the app. See Register a node to bring your first worker online.