What it does
- Ring data and a dashboard: Orbit Health syncs to it, and the dashboard shows your readings with 7-day trends.
- Your own AI agent: Anthropic, or any OpenAI-compatible provider, including a model you run yourself. Keys are stored encrypted on the server.
- The OrbitWalker voice agent: the glasses send what you said plus a text description of what’s open. The server runs the conversation and keeps it on your server.
- Voices: OpenAI, ElevenLabs, Inworld and AssemblyAI text-to-speech, with your keys.
- MCP and a data API for your own tools, using tokens with scopes and an access log of every read.
Source: github.com/Kno2gether-Labs-LTD/orbit-server.
Requirements
| You need | Details |
|---|---|
| A machine that stays on | A small Linux VPS or a home server. The image is built on the machine itself, so x86-64 and 64-bit ARM both work. |
| Memory | The server sets no fixed heap, and Java sizes itself to the memory it has. For one household, 1–2 GB of RAM is a comfortable size. |
| Docker | Docker Engine with Compose v2, running as root. Rootless Docker isn’t supported. The Tailscale override needs Compose 2.24.4 or newer. |
| A name | Tailscale with MagicDNS (recommended), or a domain with an A record pointing at the server. |
| Java 17 | Only if you build the server yourself. The release zip skips the build. |
Install with Docker Compose
This is the general install. For the private Tailscale version, follow the recommended setup, which uses the same steps with a different .env.
- Get the code.
git clone https://github.com/Kno2gether-Labs-LTD/orbit-server.git cd orbit-server - Get the server build. The Docker image packages a ready-built server and doesn’t run Gradle. Either download the release build:
or build it yourself with Java 17:curl -fsSLO https://github.com/Kno2gether-Labs-LTD/orbit-server/releases/latest/download/orbit-server.zip mkdir -p server/build/install unzip -q orbit-server.zip -d server/build/install/./gradlew :server:installDist - Configure.
cd deploy cp .env.example .env && chmod 600 .env # edit .env: see the recommended setup for Tailscale, # or set ORBIT_DOMAIN and ACME_EMAIL for a public domain - Start it.
docker compose up -d --build docker compose ps - Get the one-time setup code.
docker compose logs --tail 30 orbit
Two containers run. caddy handles HTTPS and is the only one with published ports. orbit serves plain HTTP on port 8080, on the private Compose network only, and trusts forwarded headers from Caddy’s fixed address only. Your data lives in the orbit-data volume, which Docker names orbit_orbit-data.
Never publish port 8080. It’s plain HTTP and meant only for Caddy.
First run
- Open your server at
https://your-server.your-tailnet.ts.net/. Until setup is done, every page leads to Setup. - Enter the setup code from the logs.
- Choose the admin password, 10 to 72 characters.
- There is no default password. The setup code is 30 characters in six groups. It works once and is valid for 24 hours, and the server stores only its hash.
- The code appears in the container’s output only. To get a new one, run
docker compose exec orbit /opt/orbit-server/bin/orbit-server setup-codeor restart the container. Each new code cancels the previous one, so use the most recent. - Your password is stored as a bcrypt hash (cost 12).
The dashboard
| Page | What it’s for |
|---|---|
| Overview | Your latest readings with 7-day trends, devices, recent access-log entries, the current model and active tokens |
| Pair a phone | One-time QR codes for Orbit Health and OrbitWalker |
| Devices | Paired phones with battery, firmware, scopes and last seen. Revoke any of them. |
| Agent | Provider, model and key, with a Test button. Conversations, with Delete all. |
| Voices | Voice providers, their keys and models, the default voice and a test player |
| Agent tokens | Create and revoke tokens for MCP and the data API |
| Access log | Every read of your data, and every denied attempt |
| Export | Download everything as JSON |
Sign-ins end after 30 minutes idle or 12 hours in total. Sessions are held in memory, so a restart signs you out. Changing the admin password signs out every session.
Pairing apps
- Pair a phone shows a QR code for Orbit Health and, under “Pairing OrbitWalker (AR glasses)?”, one for OrbitWalker. Both use one code. It works once, for whichever app scans it first, and expires after 10 minutes.
- From a shell:
docker compose exec orbit /opt/orbit-server/bin/orbit-server pair. Add--walkerfor OrbitWalker. - Each device gets its own token, and the server stores only its hash. Revoke a device under Devices. Its OrbitWalker conversations are deleted, and its readings stay.
- With a Tailscale or public certificate, phones trust that certificate for your exact server name. With a self-signed certificate, they pin its fingerprint.
App-side steps: Orbit Health and OrbitWalker.
Configure the AI agent and voices
Agent
- Anthropic: paste your API key and pick a model.
- OpenAI-compatible: a base URL, a model and, if needed, a key. This covers hosted providers and models you run yourself, such as Ollama (
http://localhost:11434/v1) or LM Studio (http://localhost:1234/v1). From inside Docker, usehttp://host.docker.internal:11434/v1. Plainhttp://is allowed only for local and private addresses. - Press Test to check it.
- Keys are encrypted at rest (AES-256-GCM) with a master key the server creates on first run, and are never shown again. Changing the provider or host deletes the saved key, so a key is never sent to a different host.
The agent reads your data through five read-only tools: get a metric, get sleep, a daily summary, compare to your baseline and list metrics. It sees only what the asking device’s scopes allow. It is told not to diagnose or give medical advice.
Conversations
OrbitWalker conversations are kept on your server: your words and Orbit’s final answers, up to 2,000 messages per device. A conversation starts fresh after 6 hours of quiet. Delete them all under Agent › Conversations. They are also deleted when you revoke the device. Questions from Orbit Health’s Ask tab aren’t stored on the server.
Voices
| Provider | Default model |
|---|---|
| OpenAI | gpt-4o-mini-tts |
| ElevenLabs | eleven_flash_v2_5 |
| Inworld | inworld-tts-2 |
| AssemblyAI | assemblyai-tts-1 |
Only the reply text (up to 1,500 characters) is sent to the voice provider, and the server doesn’t store or log it. Keys are encrypted like the model key. Speech-to-text happens on the phone, not on the server. OpenAI has announced that its text-to-speech models retire on 6 January 2027. The other providers are unaffected.
Agent tokens and MCP
Under Agent tokens, create a token with a name and the scopes it may read: heart, sleep, activity, stress, spo2 and profile, or all. The token is shown once and stored only as a hash. Revoking it or changing its scopes takes effect on the next request.
The MCP endpoint is POST /mcp (streamable HTTP, JSON responses) with a bearer token, and offers the same read-only tools as the agent. For example, with Claude Code:
claude mcp add --transport http orbit https://your-server.your-tailnet.ts.net/mcp \
--header "Authorization: Bearer <token>"
Tokens can end up in your shell history and in your MCP client’s config file. Start the command with a space (most shells then skip history) or delete the line afterwards, keep the config file private, and revoke the token if either leaks.
The read-only data API is at GET /v1/data/samples and GET /v1/data/sleep with the same tokens. The Access log records every read by the agent, MCP, the data API and dashboard exports. It records what was read, never the values, and denied attempts show as DENIED.
Backups and updates
Back up
Everything lives in the data volume: the database, the master key that decrypts your provider keys, and the certificate your phones trust. Back it up whole. Run this in deploy/:
docker compose stop orbit
(umask 077 && docker run --rm -v orbit_orbit-data:/data:ro eclipse-temurin:17-jre \
tar -czf - -C /data . > ~/orbit-server-backup-$(date +%F).tgz)
docker compose start orbit
To restore into an empty volume, with the server stopped:
docker run --rm -i -v orbit_orbit-data:/data eclipse-temurin:17-jre \
tar -xzf - -C /data < ~/orbit-server-backup-YYYY-MM-DD.tgz
A backup contains your health data and the key to your provider keys. Keep it private, ideally encrypted, somewhere only you can reach. See keeping backups safe.
Update
- Back up first.
- Get the new version:
git pull, then either./gradlew :server:installDistor the new release zip unpacked as in install. - Restart:
cd deploy && docker compose up -d --build - Check:
docker compose ps, then openhttps://your-server.your-tailnet.ts.net/health. It should answer with"ok":true.
Caddy is pinned to a minor version (caddy:2.11). To move on, edit the tag in docker-compose.yml, then run docker compose pull caddy && docker compose up -d caddy.
Export
The Export page downloads orbit-export-YYYYMMDD.json with your devices, readings, sleep and access log. Each export is recorded in the access log.
Troubleshooting
- Can’t find the setup code: run
docker compose logs --tail 30 orbitand use the most recent one, or make a new one withsetup-code. - Caddy won’t start after a reboot on Tailscale (“cannot assign requested address”): Docker started before Tailscale. Run
docker compose up -d, and see the reboot fix. - Ports open to the internet on a Tailscale box: the
COMPOSE_FILEline is missing from.env. Rundocker compose down, add it, and start again. - Every client seems to share one rate limit: with Docker’s userland proxy or rootless Docker, Caddy sees one address for everyone. For one person that’s harmless.
- The subnet is already in use: change the Compose subnet, Caddy’s
ipv4_addressand--trusted-proxytogether. - A phone says the server identity changed: the certificate changed. Pair again, then remove the old entry under Devices.
- Readings skipped: the server expects one phone pushing ring data. A second phone pushing can make it skip readings.
The full reference is in the README.