Remote access (Tailscale)
Use your Luna from your phone, laptop or browser anywhere, over your private Tailscale network.
Step-by-step setup for each kind of install is on Setup. This page explains what happens and how access is protected.
Share the server
npm run serve:tailscale # or: luna serve --tailscale
npm run serve:tailscale:off # stop sharingThis starts Luna and runs tailscale serve, so it's reachable at https://<this-computer>.<your-tailnet>.ts.net:8899 by devices on your tailnet only. It prints the address and Luna's access token.
- Luna keeps listening on
127.0.0.1, and Tailscale forwards to it. Leavehost=127.0.0.1. - It uses HTTPS port 8899, so other
tailscale servemappings (Ollama on 443, say) are left alone. Pick another with--https=<port>. - In PowerShell use
npm run serve:tailscale, notnpm run luna -- serve --tailscale: PowerShell drops the--and npm swallows the flag.
Connect a device
| Client | How |
|---|---|
| Desktop app | Settings → Server → Remote over Tailscale. Luna searches your tailnet and lists every shared Luna as Trusted or Needs token. If exactly one trusted server turns up, it's selected for you. Save and restart. |
| Browser | Open the ts.net address. Your own devices get in directly; others enter the token once. |
| Mobile app | Settings → Server: the address, plus the token if needed. |
How access is checked
Apps on the server's own computer call http://127.0.0.1:8899 and need nothing. Requests through tailscale serve are let in when either:
- Tailscale identity: Tailscale adds
Tailscale-User-Loginfor the signed-in user, and strips any copy a client sends. Luna trusts the account this computer is signed in to, plus any listed intailscale_trusted_logins. It only believes the header when the connection arrived on loopback, meaning it came from tailscaled on this machine, and it's never Funnel traffic. - Access token: sent in the
X-Luna-Tokenheader, or as?luna_token=for event streams. The token is indata/local_api_token.
/api/remote/hello is public: it tells a client "this is Luna, and you are or aren't authorized". The desktop app uses it for discovery. Health checks, the web UI's files, signed webhooks and OAuth callbacks also stay open. Everything else under /api needs one of the two. See server/core/access.py.
It gives full access to that Luna. To rotate it, delete data/local_api_token, restart the server, and reconnect your devices.
With Docker
tailscale serve --bg --https=8899 http://127.0.0.1:8899
docker exec luna cat /app/data/local_api_tokenTailscale's proxy reaches the container from outside it, so Luna can't confirm the account and every remote device uses the token once. Keep the container's port on 127.0.0.1, the default in the Compose files, so nothing on your network can reach Luna except through Tailscale.
Settings
| Setting | Default | What it does |
|---|---|---|
tailscale_trust_owner | true | Let in this computer's Tailscale account without a token. |
tailscale_trusted_logins | empty | More tailnet logins to trust, comma-separated. |
require_token_on_lan | false | Also require the token for direct network connections when host=0.0.0.0. |
Limits
- Google Workspace add-on: it runs on Google's servers, which can't reach a tailnet address.
- VS Code and Office add-ins have no token field yet, so they work with a server on the same computer.