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.
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 on the machine that runs your agent.
- Run
plannotator --version and verify v0.27.0 or later.
- Install Tailscale 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:
The same flag works with document annotation and the last-message picker:
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.
--tailscale works in the compiled Plannotator CLI. The Pi extension does not accept this flag.
How the connection works
Plannotator performs these steps for each --tailscale session:
-
It starts the review server on
127.0.0.1.
-
It reads the current Tailscale Serve configuration.
-
It refuses to replace an existing Serve mapping on the selected port.
-
It runs the following command with the session port:
-
Tailscale terminates HTTPS and proxies requests to the loopback server.
-
Plannotator prints the Serve URL and displays a QR code in an interactive terminal.
-
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:
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:
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:
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:
Remove the mapping for the affected port:
Do not remove mappings for unrelated ports.
Troubleshoot startup and access
The Tailscale CLI is unavailable or logged out
Run:
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 for the tailnet requirement.
The selected port already has a Serve mapping
Inspect the Serve configuration:
Remove a stale mapping with the exact command above. Keep an intentional mapping and select another Plannotator port:
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:
Tailscale documents Serve status and removal commands in its Serve CLI reference.
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:
See 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. 