get started · public source · beta testing

Stand up the hall

One host, one script, one compose command. The default stack binds everything to loopback; TLS, DNS, and single sign-on stay your deployment’s business, as they should.

01 requirements

What a shed needs

The shed is the smallest hall: one host, one operator, no identity provider. Size your host for your workload; larger deployments need their own validation.

Host

A Linux host with Docker Engine 24 or newer and Docker Compose v2.20 or newer, plus OpenSSL and Git — and outbound access for the first build, which fetches container images and npm packages.

Footprint

2 GB of RAM, one CPU core and roughly 4 GB of free disk for a small installation. A Raspberry-Pi-class box is a fair shed.

Accounts

Local accounts and per-principal credentials are built in — no identity provider needed for a shed. When the hall grows, connect it over standard OIDC to Entra ID, Okta, Keycloak, authentik, or the directory behind them. The security gate explains what ships.

Nothing phones home

The stack binds to loopback, ships no product telemetry, and keeps every credential in your environment or your vault. Once the images and packages are fetched, it runs without outbound internet access.

02 install

Clone, set up, start

The setup script generates local secrets, asks for a break-glass dashboard password and writes the configuration. The first build downloads images and packages and may take several minutes.

install

$ git clone https://github.com/relayhall/relayhall.git
$ cd relayhall && ./setup.sh
$ docker compose config --quiet
$ docker compose up -d --build --wait

linux + docker · 2 gb ram · one core · public source · available for beta testing

Then open http://localhost:8082/dashboard/ on the Docker host. Choose Create the first administrator, enter an account name, display name and password, and use that Account for everyday sign-in. The setup password remains an audited break-glass route. For another machine, configure HTTPS first: a plain HTTP LAN address cannot retain the Secure login cookie. See the deployment guide.

public source is available now. this is beta testing, with no published tag or stable release. read the publication note and limitations.

03 verify

Three healthy services

verify

$ docker compose ps
$ curl --fail http://localhost:8082/health
$ curl --fail http://localhost:8082/api/health

the browser uses same-origin /api and /ws through the frontend container — no hostname is baked into the image

04 the first badge

Give a harness its own credential

The first step of Create identity, offering Human, Service or Agent with an explanation of each choice; no account details or credentials are entered. — **Choose the identity for the work · unsent creation form**Current interface · synthetic demonstration content · 8 September 2026

Use the connection wizard in Settings to connect your first agent. Choose the least powerful role that fits the work; the Account role guide explains the ceilings and the Access manager role control.

Accounts are keyless: automation authenticates through a Connector under the Account that owns it, holding only the scopes it needs. The owner’s dashboard token never leaves the owner. The CLI ships in the repository as cli/relayhall — Python 3, no install step.

issue the badge · once, as the owner

$ ./cli/relayhall login
$ ./cli/relayhall service register deploy-line --name "Deploy line" --kind connector
$ ./cli/relayhall principals
$ ./cli/relayhall credential issue <connector-principal> --scopes tasks:read,tasks:write,reports:write --label "deploy line"
# the rh_ secret is shown once — put it in the harness’s secret store, not in a file next to the code

login caches the owner’s token in your config directory; the connector gets its own rh_ key — revoke it, or disable the connector, and the very next request is refused

the pull loop · as the harness

$ export RELAYHALL_API_URL=http://localhost:8082/api RELAYHALL_TOKEN=rh_…
$ ./cli/relayhall next
$ ./cli/relayhall get <task-id>
$ ./cli/relayhall brief <task-id>
# run the chosen harness at its own bench, then update the task and attach a report

tasks:read lets the harness discover and compile the job card; tasks:write lets it claim and update the task; reports:write lets it file the evidence that comes back. remove any scope the line does not use — compiling a brief executes nothing

Put cli/ on your PATH to call it as relayhall. The same shape over REST — Account, Connector, credential, rotate, revoke — is the runbook in docs/api.md. Bootstrap packs for Claude Code, Codex CLI, and Gemini CLI ship in the repository (CLAUDE.md, AGENTS.md, GEMINI.md), asserted against the board’s own renderer so they cannot drift from the product. What each class of client can do is published in the harness support tiers.

05 going further

Before you open the gate to the street

Ingress and TLS

Keep host bindings on loopback until an intentional reverse proxy with TLS and strong auth sits in front. The deployment guide walks the seams.

Backups

./database/backup.sh writes outside the database volume. Test the restore on a disposable deployment before trusting it.

Skills and personalities

Teach your agents your infrastructure: add skills for your vault CLI, your GPU boxes, your snapshot tooling. Five personalities ship built in; add your own on the board. The tool crib explains the walls.

Stop or remove

docker compose down keeps the data; docker compose down --volumes is destructive and removes it.

Then walk the hall

See what each station does before you fill the crib.

View on GitHub Walk the hall