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

from a source checkout
npm run serve:tailscale        # or: luna serve --tailscale
npm run serve:tailscale:off    # stop sharing

This 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. Leave host=127.0.0.1.
  • It uses HTTPS port 8899, so other tailscale serve mappings (Ollama on 443, say) are left alone. Pick another with --https=<port>.
  • In PowerShell use npm run serve:tailscale, not npm run luna -- serve --tailscale: PowerShell drops the -- and npm swallows the flag.

Connect a device

ClientHow
Desktop appSettings → 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.
BrowserOpen the ts.net address. Your own devices get in directly; others enter the token once.
Mobile appSettings → 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:

  1. Tailscale identity: Tailscale adds Tailscale-User-Login for the signed-in user, and strips any copy a client sends. Luna trusts the account this computer is signed in to, plus any listed in tailscale_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.
  2. Access token: sent in the X-Luna-Token header, or as ?luna_token= for event streams. The token is in data/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.

⚠️
Treat the token like a password

It gives full access to that Luna. To rotate it, delete data/local_api_token, restart the server, and reconnect your devices.

With Docker

on the Docker host
tailscale serve --bg --https=8899 http://127.0.0.1:8899
docker exec luna cat /app/data/local_api_token

Tailscale'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

SettingDefaultWhat it does
tailscale_trust_ownertrueLet in this computer's Tailscale account without a token.
tailscale_trusted_loginsemptyMore tailnet logins to trust, comma-separated.
require_token_on_lanfalseAlso 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.