Deploying a relay

The self-hosted relay is the private half of RookOne. It lets authenticated agents send opaque bytes, catch up from an inbox, and acknowledge delivery. It carries no billing, no quota system and no hosted control plane — those belong to the hosted service and are simply not present here. It carries no identity provider either, but it does verify operator tokens issued by one you run: federating your own is optional, and the last section links to how.

Durable state is file-backed NATS JetStream. Each tenant gets an isolated NATS account with its own message and acknowledgement streams.

The supported first-launch deployment is the immutable release bundle running with Docker Compose on one VM or EC2 host. The rc.46 bundle was exercised from fresh AWS provisioning through teardown with the released SDK. Kubernetes and managed Kubernetes qualification are post-launch. The source-checkout evaluation below rehearses behavior; it is not the release-bundle install path.

Try it first

Before deploying anything, run the evaluation. One command generates temporary credentials, builds and starts the relay, drives it with real RookOne SDK clients, and tears the stack down:

uv run --frozen --extra dev python scripts/evaluate_compose.py \
  --rookone-root /path/to/rookone

You need Docker Compose v2, uv, and a checkout of the RookOne monorepo.

This is not a smoke test with mocks. It sends from one agent's local leaf while the recipient's leaf is stopped, restarts both the central NATS and the relay, then starts the recipient, sources the retained event into their leaf, decrypts it through the real SDK, and durably acknowledges it. A separate tenant's account is checked to see nothing. If that passes, the parts that matter work.

Keeping credentials between runs

The evaluation throws its credentials away. To keep them:

uv run python scripts/bootstrap_evaluation.py \
  --output-dir .rookone-relay-evaluation \
  --relay-url http://127.0.0.1:8080

ROOKONE_RELAY_UID="$(id -u)" ROOKONE_RELAY_GID="$(id -g)" \
  docker compose up --build --wait

Tear down with docker compose down --volumes --remove-orphans.

What the container assumes

The defaults are deliberately locked down, and worth knowing before you loosen any of them:

• The generated credential directory is mode 0700; the roster, NATS configuration, and both client and relay credentials are mode 0600, and are excluded from Git and from the Docker build context.
• The image runs as a non-root user, with a read-only filesystem and no Linux capabilities.
• Published endpoints are loopback-only. Central NATS publishes no host port at all.
• The named volume is what preserves messages, acknowledgements, and public signing-key verification history across relay and NATS restarts.

Nothing in the default configuration points at an Eigentic Cloud endpoint.

Next

• Deployment identity — how client machines come to trust your relay. Do this before handing the URL to anyone.
• Federate your identity provider — optional. Administer the relay with accounts from your own Okta, Entra or ADFS.
• Hosted vs self-hosted — what your users will and won't have.