> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Review Plannotator Sessions over Tailscale

> Open Plannotator review and annotation sessions from another device through Tailscale Serve without binding the server beyond localhost.

Use `--tailscale` to open a Plannotator session from another device on your tailnet. Plannotator keeps its server on `127.0.0.1` and publishes an HTTPS proxy through [Tailscale Serve](https://tailscale.com/docs/features/tailscale-serve).

The session is available only through your tailnet. Plannotator uses Serve, never Tailscale Funnel.

## Prerequisites

Before you start, verify this configuration:

* [Install or update Plannotator](/open-source/start/installation) on the machine that runs your agent.
* Run `plannotator --version` and verify `v0.27.0` or later.
* [Install Tailscale](https://tailscale.com/download) on the agent host and review device.
* Connect both devices to the same tailnet.
* Permit the review device to reach the agent host through your Tailscale access rules.
* Enable HTTPS certificates for the tailnet. On first use, Tailscale can open an administrator consent flow.

The review device needs Tailscale and a browser. It does not need the Plannotator CLI.

Run `tailscale status` on the agent host. Before you start Plannotator, resolve any login or daemon error.

## Start a remote review

Run Plannotator on the agent host:

```bash theme={null}
plannotator review --tailscale
```

The same flag works with document annotation and the last-message picker:

```bash theme={null}
plannotator annotate path/to/spec.md --tailscale
plannotator annotate-last --tailscale
```

Plannotator prints the HTTPS session URL to standard error. An interactive terminal also displays a QR code.

Verify that Tailscale is connected on the review device. Scan the QR code or open the printed URL.

<Note>
  `--tailscale` works in the compiled Plannotator CLI. The Pi extension does not accept this flag.
</Note>

## How the connection works

Plannotator performs these steps for each `--tailscale` session:

1. It starts the review server on `127.0.0.1`.

2. It reads the current Tailscale Serve configuration.

3. It refuses to replace an existing Serve mapping on the selected port.

4. It runs the following command with the session port:

   ```bash theme={null}
   tailscale serve --bg --https=<port> http://127.0.0.1:<port>
   ```

5. Tailscale terminates HTTPS and proxies requests to the loopback server.

6. Plannotator prints the Serve URL and displays a QR code in an interactive terminal.

7. Plannotator removes its Serve mapping at normal session exit.

Mappings on other ports remain unchanged. A pre-existing mapping on the selected port stops startup instead of being replaced.

`--tailscale` forces local mode for that session. It overrides `PLANNOTATOR_REMOTE`, SSH detection, and `PLANNOTATOR_URL_HOST`.

## Understand the security boundary

Tailscale Serve makes the session reachable through the tailnet, not the public internet. Tailscale access rules still govern which devices can reach the host.

Plannotator does not add a login screen or per-request authentication. Every permitted tailnet peer can use the session UI and its local API.

The embedded agent terminal is disabled for `--tailscale` sessions. Enable it only for a tailnet where every permitted peer is trusted:

```bash theme={null}
PLANNOTATOR_AGENT_TERMINAL_REMOTE=1 plannotator annotate path/to/spec.md --tailscale
```

This variable exposes command execution through the session UI. Its terminal token is not an authentication boundary.

## Advertise a Tailscale host in remote mode

`PLANNOTATOR_URL_HOST=auto` solves a different problem. It produces a reachable URL for Plannotator remote mode without starting Tailscale Serve.

When another system already provides private routing or port forwarding, use this configuration:

```bash theme={null}
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_URL_HOST=auto
plannotator review
```

Plannotator first reads the machine's Tailscale MagicDNS name. A fallback requires exactly one Tailscale IPv4 address in `100.64.0.0/10`.

Detection runs once per process. Detection failure prints a warning and falls back to `localhost`.

This value changes only the advertised URL. Remote mode still binds to `0.0.0.0`, and you remain responsible for network access.

To make the value persistent, save it in `~/.plannotator/config.json`:

```json theme={null}
{
  "urlHost": "auto"
}
```

`PLANNOTATOR_URL_HOST` takes precedence over `urlHost` in the configuration file. An empty environment value suppresses the saved value.

## Remove a stale Serve mapping

Plannotator removes its mapping after normal exit, `SIGINT`, `SIGTERM`, or `SIGHUP`. Failed cleanup retries once and prints the manual command.

`SIGKILL` or a host restart can leave the background mapping active. Inspect the current configuration:

```bash theme={null}
tailscale serve status
```

Remove the mapping for the affected port:

```bash theme={null}
tailscale serve --https=<port> off
```

Do not remove mappings for unrelated ports.

## Troubleshoot startup and access

### The Tailscale CLI is unavailable or logged out

Run:

```bash theme={null}
tailscale status
```

Install Tailscale or restore the daemon and sign in. Then run the Plannotator command again.

### Tailscale requests HTTPS approval

Complete the administrator consent flow that Tailscale displays. Then run the Plannotator command again.

See [Set up HTTPS certificates](https://tailscale.com/docs/how-to/set-up-https-certificates) for the tailnet requirement.

### The selected port already has a Serve mapping

Inspect the Serve configuration:

```bash theme={null}
tailscale serve status
```

Remove a stale mapping with the exact command above. Keep an intentional mapping and select another Plannotator port:

```bash theme={null}
PLANNOTATOR_PORT=19433 plannotator review --tailscale
```

### The URL does not open on the review device

Verify that both devices are connected to Tailscale. Verify that access rules permit the review device to reach the host.

Then inspect the active mapping:

```bash theme={null}
tailscale serve status
```

Tailscale documents Serve status and removal commands in its [Serve CLI reference](https://tailscale.com/docs/reference/tailscale-cli/serve).

### The QR code is absent

When standard error is an interactive terminal, Plannotator displays the QR code. Use the printed HTTPS URL in other environments.

### A gated annotation cannot start

A Tailscale publishing failure returns exit code `1` for a normal command. A strict annotation gate returns exit code `2`.

Strict gates use `--require-approval` or `--result-file`. A startup failure does not create a result file.

## Integration limits

Only `review`, `annotate`, `annotate-last`, and its `last` alias accept `--tailscale`. Other subcommands reject the flag.

Agent hooks do not add `--tailscale` automatically. When you need tailnet access, start a file gate directly:

```bash theme={null}
plannotator annotate path/to/plan.md --tailscale --gate
```

See [Remote access](/open-source/remote-access) for trusted private networks, SSH tunnels, and development-container forwarding.

Last verified on August 12, 2026, against Plannotator `v0.27.0` and product commits `5f33b72` and `ed6f44b`. Maintained by the Plannotator project.