Three processes
The relay drives the sessions through the host, over a socket in a folder only you can open. So a restart of the relay does not touch the sessions: a turn in progress goes on, and the panel shows the same output.
Restarts and stops
- After a restart, the new relay takes back each session as it is: the same process, desk, conversation and turn.
- After a full stop, each session comes back with
claude --resume, in the same folder, with its title, task and role. A session that fails to come back is tried again on the next start, up to three times. - Two relays on one state folder could erase each other’s files. So a new relay looks for old copies of itself with
ps, and stops one that has no relay process left.
Hooks while the relay is down
When the relay does not answer, as during a restart, the hook adds the event tohook-queue.jsonl in the room’s state folder, with the time it ran. When the relay starts, it takes its sessions back first, then applies the queued events in the order they happened.
How the room updates itself
After a merge, the relay pulls the new code into its own folder. If only page files changed, the page reloads. If the relay’s own files changed, it waits until no session is in a turn, then restarts on the new code. The sessions keep running through it. With the rollback switch on (RELAY_ROLLBACK=1), an update goes further:
1
One merge at a time
It takes main forward one merge at a time, oldest first, so a failure points to one merge.
2
A check after each restart
Within 60 seconds, the new relay must answer, serve the room page, and take back its sessions.
3
Rollback on failure
If the check fails, the supervisor checks out the last commit that passed and starts the relay there. It rolls back only once in a row, and never over changes you have not committed.
Worlds
A room is one world. A world is any page withwindow.run: the relay passes commands from callers such as curl, a script or a hook to the page, and streams the page’s events back. The relay knows no world by name. A folder with a world.json is a world, and each world can run on a relay of its own, with its own port and key.
For every detail, see Running it and The relay API in the technical manual.