> ## Documentation Index
> Fetch the complete documentation index at: https://docs.building58.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Building58 architecture: sessions that outlive the relay

> Inside Building58: the supervisor, relay and session host, how sessions survive a restart, how hooks wait while the relay is down, and how it updates itself.

The Building58 relay restarts every time it pulls new code, and the sessions it runs should not notice. To make that work, the room splits the job across three processes, keeps its state in files, and checks each new version of itself before it trusts it.

## Three processes

| Process | File | What it does |
| - | - | - |
| Supervisor | [`relay/supervisor.js`](https://github.com/bfalkowski/building58/blob/main/relay/supervisor.js) | Runs the relay as its child. When the relay exits with code 75, it starts it again on the same port with the same key. |
| Relay | [`relay/server.js`](https://github.com/bfalkowski/building58/blob/main/relay/server.js) | Serves the room page, hears hooks, types into sessions, runs Autopilot, and keeps the room's state in files. |
| Session host | [`relay/session-host.js`](https://github.com/bfalkowski/building58/blob/main/relay/session-host.js) | Runs each session's terminal and its `claude` process, and keeps the last 256 KB of each session's output. |

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 to `hook-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.

The relay and the session host each say which version of their messages they speak. The relay never sends the host a message its version does not know.

## Worlds

A room is one world. A world is any page with `window.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](https://building58.ai/docs/manual/running.html) and [The relay API](https://building58.ai/docs/manual/relay.html) in the technical manual.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.