Remote Hosts

Daemons on the same network discover each other automatically, and — once two of them trust each other — sessions can be created and run across the pair. A typical setup: a workstation hosts the heavy sessions while you drive from a laptop.

A quick example

Say you're on your laptop and want a migration to run on your studio workstation across the room. Both machines just need the daemon up — any actor command starts it.

Trust is mutual: each machine trusts the other, confirming its fingerprint against actor servers list. On studio:

actor servers list             # laptop shows up, untrusted
actor servers trust sha256:…   # paste laptop's confirmed fingerprint

And on laptop:

actor servers list             # studio shows up, untrusted
actor servers trust sha256:…   # paste studio's confirmed fingerprint

With both sides trusting, the two daemons connect. Now create a session on studio with --host:

actor new migrate --host studio --prompt "Port the config loader to the new schema."

It runs in a worktree on studio and reports back like any local session. From your main session you'd just ask — "spawn a session on studio to port the config loader" — and main passes host for you. That's the whole loop; the rest of this page explains each piece.

Discovery

Each daemon advertises itself over mDNS (the _actor._tcp.local. service), publishing its name, host, port, version, and a TLS fingerprint. Other daemons on the LAN see it without any configuration. Both machines need actord running (any actor command auto-spawns it). List what's visible:

actor servers list

Each row shows a fingerprint (a hash of the daemon's TLS certificate) and its state: self, trusted (you trust it), or connected (you trust it and it trusts you back). A freshly-discovered peer is untrusted and can't do anything yet.

If multicast isn't available (a sandboxed CI box, a locked-down network), the daemon falls back to unix-socket-only: everything local keeps working, and peer discovery is disabled.

Trust is mutual

Trust runs both ways: a connection only forms once each daemon has trusted the other. The mTLS handshake enforces it — each side checks the other's certificate against its own trust store, so trusting a peer one-way leaves it trusted but never connected, and no sessions can cross until the other side trusts you back.

On each machine, record the peer:

actor servers trust <fingerprint-or-name>

Pass the sha256:… fingerprint you confirmed out of band — that's the recommended path, since the fingerprint is the peer's real identity and works even when it isn't currently visible. You can also pass the name from the list as a shortcut, but that simply trusts whatever fingerprint is advertised under that name right now — no out-of-band check — so a peer impersonating the name would be trusted. Run the command on the other machine too, for the reverse direction.

Run sessions on a host

Target a connected host with --host <fingerprint-or-name>. It's accepted by the session commands — new, run, stop, discard, and show — so the whole lifecycle works across the pair:

actor new migrate --host studio --prompt "Port the config loader."
actor run migrate --host studio "Now add tests."
actor discard migrate --host studio

The session lives in a worktree on the remote host and reports back the same way local ones do — to the daemon it's just another session. From your main session you don't type the flag: ask for work "on studio" and main passes host to its new_session tool. Repos the host needs are cloned under its repo_dir (configurable in settings.kdl).

Trust is the gate for everything cross-host. Until both daemons trust each other, neither will provision sessions on the other.

Revoking

Remove a peer from the trust store at any time:

actor servers untrust <fingerprint-or-name>

After that, the daemon refuses to provision anything on it again until you re-trust.