Docs

Self-hosting the relay

The relay is one static binary (also shipped as a container). It stores public keys, pairing tickets and push handles, forwards sealed messages, and nothing else. Put it anywhere all your devices can reach over HTTPS.

Run the binary

Download orbit for your platform from the download page, then:

orbit relay --addr :8080 --data ./relay-data

• --addr is the listen address (also ORBIT_ADDR).
• --data is the state directory; back it up if you like, it is small (also ORBIT_DATA).

Run with Docker

A small image is all it takes: the same orbit binary, running as a relay.

FROM debian:stable-slim
ADD https://dl.agentorbit.app/dl/orbit-linux-amd64 /usr/local/bin/orbit
RUN chmod +x /usr/local/bin/orbit
EXPOSE 8080
VOLUME /data
ENTRYPOINT ["orbit", "relay", "--addr", ":8080", "--data", "/data"]

docker build -t orbit-relay .
docker run -d --name orbit-relay --restart unless-stopped \
  -p 8080:8080 -v orbit-relay-data:/data orbit-relay

Use orbit-linux-arm64 on ARM hosts. Anything after the image name is passed to orbit relay as flags, for example --registration-token.

Put it behind HTTPS (we recommend Tailscale)

Browsers and phones need HTTPS, and a tailnet keeps the relay off the public internet entirely. On the relay host:

tailscale serve --bg 8080

Your relay is now at https://<host>.<tailnet>.ts.net for every device on your tailnet, including your iPhone with the Tailscale app. Caddy, nginx or a Kubernetes ingress work just as well if you prefer.

Point your devices at it

In the Mac app, choose Self-hosted and paste the relay URL. Pair your iPhone and servers from Settings as usual; the pairing code carries the relay address, so they find it on their own.

iPhone push for a self-hosted relay

Apple only lets Orbit's own push key reach the iPhone app, so your relay sends sealed push envelopes through our Push Gateway at push.agentorbit.app. It costs $5 a year because it is our running cost. Buy a Push Gateway key, then start the relay with it:

orbit relay --addr :8080 --data ./relay-data --push-gateway-key ORBIT_PUSH-…

Or set ORBIT_PUSH_GATEWAY_KEY in the environment. Without a key, the relay runs fine; phones just do not get pushes.

Public relays: require a registration token

If the relay is reachable from the internet (not only your tailnet), set a registration token so strangers cannot create meshes on it. Your own devices need the token once, when the first Mac creates the mesh.

orbit relay --addr :8080 --data ./relay-data --registration-token $(openssl rand -hex 24)

Also available as ORBIT_REGISTRATION_TOKEN.

Updates and the license

Your Self-Hosted key (ORBIT_SELF-…) is entered in Orbit, not passed to the relay. License activation arrives in an upcoming update; the key from your checkout email will work then, and the relay runs without it in the meantime.

Once activated, the license is checked offline against a public key built into the relay, so the relay never depends on our servers to keep running. It accepts any build released within your year of updates. A newer build will ask for a renewal and the older one keeps working. Renewing ($25) adds a year from the later of your current end date and the renewal date, so renewing early loses nothing.

orbit update reads the release feed and replaces the binary in place. For Docker, pull the new image tag.

Flags at a glance