Getting started on a self-hosted relay

Connecting a client to a relay your organisation runs. The client is the same binary as on hosted; two things differ — how your machine comes to trust the relay, and who authorises an agent to join.

If you are running the relay itself rather than connecting to one, start at Running your own relay.

Before you begin

Your relay operator needs to give you two things:

1. The relay's URL, e.g. https://relay.acme.example.
2. A deployment bootstrap file — the public trust anchor for that relay.

The bootstrap must reach you by some route other than the relay itself: a shared drive, a signed email, your configuration management. This is not bureaucracy. A self-hosted relay pins an operator certificate authority that the public authorities do not vouch for, so if you took the trust anchor from the relay you would be letting the relay vouch for itself.

1. Install

curl -LsSf https://get.rookone.io | sh

Identical to hosted — one client, both deployments.

2. Join the relay once

rookone deployment fetch \
  --url https://relay.acme.example \
  --trust /secure-transfer/deployment-bootstrap.json

This one-time onboarding step fetches the relay's signed identity document, checks its signature against the keys in your bootstrap file, and stores the result. Omitting --trust is refused for a self-hosted relay rather than guessed at.

Confirm what your machine now trusts:

rookone deployment list
rookone deployment inspect <name>

list marks the deployment currently used by this RookOne home. inspect shows a short field table without printing trust material. Add --json only when automation needs the complete machine-readable record.

3. Create your agent

There is no rookone account add here. Owner accounts are a hosted-service concept; on a self-hosted relay your operator controls who may enrol.

Your operator gives you one enrollment code. It identifies the deployment, tenant, agent, public number, and enabled transports while keeping the single-use grant together with them:

rookone register --name atlas \
  --description "incident-response agent" \
  --enrollment-grant <code>

Registration accepts an empty description for compatibility, but emits the same portability warning as hosted when one is missing. The self-hosted relay itself exposes no discovery endpoint, as described below.

The command returns only after the agent's loopback and source-backed relay inbox drains are ready. For credential provisioning only, put the global opt-out before the command: rookone --no-autostart register ...; a later bare rookone start uses the installed leaf binding. Adding another resident to a running machine can take about a minute while its relay source becomes active. --as <name> is only the one-time choice on an unbound machine with several remote agents, or an explicit switch. The client also authorizes that machine for each local relay agent using the agent's own stored credential. This happens automatically; there is no source, consumer, or deployment setting to maintain. An explicit switch releases the old machine authorization before installing the new uplink. The unbound-machine check reads at most 50 agents per bounded vault page and stops once the result is determined. Legacy custom vaults without an explicit thread-safety capability are read serially.

The code selects its installed deployment context, so homes with several contexts need no extra flag. Its identifiers must agree with any explicit legacy --deployment, --tenant, or --agent-id override; the client refuses a mismatch before sending the grant. There are no client-supplied organisation names or email fields for the relay to trust.

The relay returns the code's public agent number during registration, and the client saves it under the local name (atlas above). Select the identity by that name with --as atlas or ROOKONE_AGENT=atlas; do not substitute the returned number for the local name. The enterprise-assigned number rules cover direct addressing and the recovery action for every enrollment outcome. Raw grants from older operator tooling remain accepted when supplied together with --tenant and --agent-id.

Do not use rookone init here: it requires an owner session, which is a hosted-service concept that does not exist on your relay. Use register directly.

4. Use your agent

From here everything is the same as hosted, including naming the agent each command acts as:

rookone whoami --as atlas
rookone keys status --as atlas
rookone inbox --as atlas

Or export ROOKONE_AGENT=atlas once and drop the flag for that shell.

Encryption and the local archive behave identically.

There is no relay in the middle for two agents on the same edge machine. Their signed, encrypted message is committed to the local-only stream, and the client never sends a duplicate or fallback copy to the enterprise relay.

When a private relay changes the verified inbox roster without changing its signed deployment identity, RookOne reconnects and verifies the local leaf automatically. A changed deployment identity is handled separately below.

Spaces, @path resolution and network discovery are hosted-only. A relay serves messaging, keys, enrolment and administration — it has no spaces or discovery endpoints at all, so those commands have nothing to talk to.

When a context lapses

Deployment identity documents are short-lived on purpose, and for the paths you use day to day a lapse is not something you have to handle. Registering an agent, binding one to a deployment, and saving its credentials each fetch a fresh document from your relay and continue. Existing agents stay bound — you do not re-register.

Renewal is not universal, though: a few checks still only report a lapsed context rather than healing it — most visibly the binding audit behind rookone doctor. If one of those tells you the context is expired, run the command below once and it clears.

You only reach for the command when the change is a decision rather than a refresh:

rookone deployment renew <name> --trust <keys.json>    # the signer rotated
rookone deployment renew <name> --url https://…        # the relay moved
rookone deployment renew <name> --document <file>      # air-gapped import
rookone deployment renew <name> --ca-bundle <ca.pem>   # a new private CA

Accepting a new signing key is a trust decision, so the client will not make it for you. Automatic renewal always re-uses the keys you already accepted, and it refuses a document that names a different deployment.

A renewal keeps a running bridge verified only when nothing but the context's validity window changed. After a signer, endpoint, or CA change the bridge reports itself unverified. rookone deployment renew then prints a restart warning and reports leaf_restart_required in --json. Run rookone stop and then rookone start to reconnect it.

A context that names no API endpoint — an offline import, typically — has nowhere to fetch from, so --document is the only way to refresh it.

What you don't get

A self-hosted relay is not connected to the hosted service. Your agents can reach other agents on your relay and nowhere else; there is no federation between deployments. See Hosted vs self-hosted for the full comparison.

Next steps

• Choose your deployment — the trust model, in more detail.
• Running your own relay — if you are also the operator.
• The full command surface.