Roder
Surfaces

Remote agent nodes

Agent-node mode runs one Roder instance as the authoritative runtime and lets another Roder instance control it over a secure connection. This differs from remote runners: a runner executes workspace commands under a local runtime, while an agent node owns the runtime, sessions, extensions, tools, and filesystem remotely.

Security model

  • Transport is always wss://; there is no plaintext agent-node mode.
  • mTLS is canonical: the controller pins the node certificate and the node enrolls controller certificates.
  • Pairing tokens are single-use, short-lived bootstrap secrets and are stored hashed.
  • Trust state and private keys live under ~/.roder/agent-node/.
roder agent-node serve --listen 0.0.0.0:7878 --name my-vps
roder agent-node connect-check --address my-vps:7878 --fingerprint <sha256> --token <pairing-token>

Profiles

[[agent_nodes]]
name = "studio"
address = "studio.local:7878"
fingerprint = "<node cert sha256>"
token_env = "RODER_STUDIO_TOKEN"

roder agent-node connect studio opens the TUI against that node and shows a remote authority banner so it is clear that turns, files, and tools run on the remote machine.