Use remote access when Plannotator runs on one machine but you want to review from a phone, tablet, or another computer. You are not deploying a persistent Plannotator server. Each command starts a temporary session that normally exits after you approve, send feedback, or close it.
Choose a connection
Plannotator does not add a login screen or per-request authentication to a remote session. Do not expose its port to the public internet or an untrusted network.
Use Tailscale
Before you start:
- Install Plannotator
v0.27.0 or later on the machine that runs your agent.
- Install Tailscale and connect the agent host and review device to the same tailnet.
- Enable HTTPS certificates for the tailnet.
- Permit the review device to reach the agent host through your Tailscale access rules.
Then start the session with --tailscale:
The same flag works for document annotation and the last-message picker:
Plannotator prints an HTTPS URL and displays a QR code in an interactive terminal. It keeps the temporary server on 127.0.0.1 and uses Tailscale Serve as the HTTPS proxy.
--tailscale works in the compiled Plannotator CLI. The Pi extension does not accept this flag.
Use trusted Wi-Fi, a LAN, or another private VPN
Set remote mode and advertise a hostname or IP address that the other device can reach:
Replace devbox.internal with a resolvable hostname, an IPv4 address such as 192.168.1.42, or a bracketed IPv6 address such as [fd7a:115c:a1e0::42].
PLANNOTATOR_REMOTE=1 binds the temporary server to 0.0.0.0. PLANNOTATOR_URL_HOST changes only the URL that Plannotator prints. It does not change the bind address. The value must contain only a hostname or IP address, with no scheme, port, path, credentials, or whitespace.
Remote mode uses port 19432 by default. Set a fixed port or a range when you need different network or concurrency behavior:
The compiled CLI prints the complete URL and displays its QR code when standard error is an interactive terminal. Pi reports the reachable URL but does not display the QR code.
The core review, annotation, and approval flows work over plain HTTP. Browser features that require a secure context, including creating an encrypted short share link, require HTTPS.
PLANNOTATOR_URL_HOST=auto detects a Tailscale MagicDNS name or tailnet IPv4 address. For WireGuard, ZeroTier, a corporate VPN, or a LAN, set the hostname or IP address explicitly.
Forward a session over SSH
From your local computer, connect with the same local and remote port:
Inside that SSH session, start Plannotator with a fixed port:
Open http://localhost:19432 on your local computer if Plannotator does not open it automatically.
Remote mode listens on every interface of the remote host. The SSH tunnel does not stop another network peer from reaching port 19432 through a different interface. Keep the port blocked by the host firewall and network policy.
Forward a development-container port
Add the fixed port and remote mode to devcontainer.json:
Rebuild the container, start a review, and open the forwarded port from the editor’s Ports view. Keep its visibility private. Setting PLANNOTATOR_PORT without PLANNOTATOR_REMOTE=1 is not enough because local mode binds to 127.0.0.1 inside the container.
VS Code Remote and development containers usually provide a BROWSER helper that opens the forwarded URL on your local computer. Plannotator uses that helper when it is available. You can also set PLANNOTATOR_BROWSER to a browser or script.
Control deprecated link sharing
Remote access and link sharing are separate features. A live remote session lets another browser make the decision while the agent waits. The deprecated OSS sharing flow creates an asynchronous link that another person returns later.
Disable link sharing when you only need the live remote session:
The variable applies to the compiled CLI, Pi, and integrations that use Plannotator’s shared configuration resolver. An explicit OpenCode share setting takes precedence.
When sharing remains enabled, a remote Markdown session can produce a complete share URL in addition to the live session URL. The Markdown is inside that complete URL and can remain in terminal logs or shell capture.
With sharing enabled, remote raw HTML uses the paste service because it cannot use the hash-only Markdown format. The compiled CLI encrypts and uploads the HTML when the remote session starts. Pi serves the HTML through the forwarded live session but does not upload it automatically at startup. Disable sharing before opening sensitive remote HTML when that upload is not intended.
Protect the annotate-mode agent terminal
The embedded agent terminal in annotate mode is disabled during remote and --tailscale sessions. Enabling it allows the browser to run commands on the machine that hosts Plannotator:
Use this setting only when every device and network path that can reach the session is trusted. The terminal token is not an authentication boundary.
Troubleshoot the connection
During a session, check the server on the machine running Plannotator:
A working session returns 200. Replace 19432 if you selected another port. If the other device cannot connect, check these items:
- The process that started Plannotator inherited
PLANNOTATOR_REMOTE=1.
- The hostname or IP address resolves from the review device.
- The firewall permits only the intended private path to the selected port.
- An SSH or development-container forward uses the same port as Plannotator.
- Tailscale is connected on both devices and its access rules permit the connection.
See Troubleshooting for port conflicts and host-specific checks.
Last verified on August 12, 2026, against Plannotator v0.27.1 and product commits b69742c, 5f33b72, and ed6f44b. Maintained by the Plannotator project. 