# Tailscale

> Put Falak servers on your Tailscale tailnet, make sites reachable only from your own devices, and close the panel to everyone outside the tailnet.

Source: https://falak.sh/docs/guides/tailscale/

Falak can put your servers on your organization's [Tailscale](https://tailscale.com) tailnet. Two things follow: a
site can be reachable **only from your tailnet devices** (everyone else gets 403), and the Falak **panel** can be closed
the same way.

## How it works

Every server that joins the tailnet advertises **its own public IPs** (`<ipv4>/32`, `<ipv6>/128`) as routes. A device
that accepts routes sends traffic for that address through the tunnel, so it reaches the server with its tailnet
address as the source. A "Tailscale only" site is then an edge allowlist of the tailnet ranges. Nothing else changes:
DNS stays the public A / AAAA records, Let's Encrypt still reaches the server, and agents and webhooks keep using the
public path. Falak's servers never accept routes themselves, so server-to-server traffic stays public too.

## Set up Tailscale

1. In the Tailscale admin console, [generate an auth key](https://login.tailscale.com/admin/settings/keys): **reusable**,
   **pre-approved**, tagged `tag:falak`.
2. Let the tag's routes be approved automatically, in **Access controls**:

   ```json
   {
     "autoApprovers": {
       "routes": {
         "0.0.0.0/0": ["tag:falak"],
         "::/0": ["tag:falak"]
       }
     }
   }
   ```

   `0.0.0.0/0` only means "any route this tag advertises": servers advertise their own `/32` and `/128`, nothing else.
   Without auto-approval, approve each server's routes by hand in the admin console.
3. Make your devices accept routes. macOS, Windows, iOS and Android do by default; on Linux run
   `tailscale set --accept-routes`.

## Set up Falak

1. **Settings → Tailscale:** paste the auth key and click **Save key**.
2. **Servers → the server → Network → Tailscale → Join the tailnet.** Falak installs Tailscale from the official static
   release and the status goes from *installing* to *active*. Joining needs agent v0.25 or newer.
3. Check the routes are **approved**. If the server shows "Approve the server's routes in the Tailscale admin console",
   approve them there (or auto-approve `tag:falak`), then refresh.
4. **Site → Networking → Tailscale only.** Turn it on. Falak refuses unless every server of the site is on the tailnet
   with its routes approved, and tells you which server to fix. The site's own *Allow only* entries and Falak's
   own health and uptime checks still get in.

Keep the site's domains **DNS only**: a Cloudflare-proxied (orange) record reaches the server from Cloudflare's
addresses, not yours.

**Leave the tailnet** from the same Network tab. Falak refuses while a Tailscale-only site runs on that server (turn
the switch off first), and refuses to remove the auth key while servers are on the tailnet.

## The panel

Once the control-plane machine is on the tailnet (join it like any server), close the panel to everyone else. On that
machine, as root:

```bash
falak-ctl panel-access tailnet   # browsers outside the tailnet get 403
falak-ctl panel-access status
falak-ctl panel-access public    # reachable from anywhere again
```

`tailnet` refuses unless the machine is on the tailnet and its route is approved, so you cannot lock yourself out by
accident. It sets `FALAK_PANEL_ALLOW` in `/opt/falak/.env` and recreates the edge; DNS and certificates do not change.

Browser paths on the panel domain (and the agent API host) answer 403 to other addresses. **These stay public**, because
machines call them: `/agent/*`, `/install/*`, `/api/*` (token API, Git webhooks, deploy hooks, builders),
`/terminal/v1/*` (CLI consoles), `/otlp/*`, `/up` and public status pages.

Over SSH to the control-plane machine, run `falak-ctl panel-access public`.

## Limits

- **Cloudflare-proxied domains do not work** with Tailscale only, or with a closed panel: the edge sees Cloudflare's
  address. Keep those records DNS only.
- **Workloads of your organization running on the control-plane machine** also reach its Tailscale-only sites (they
  share the machine's addresses that Falak's own checks use).
- **Deleting a server does not remove its device** from the Tailscale admin console. If the server was offline, remove
  the device there yourself.
- Needs **agent v0.25 or newer** on each server.
- Not included yet: the Tailscale API (auto-approving routes, listing devices), MagicDNS names, `tailscale serve` and
  `falak.yaml` support.
