Plannotator works in remote environments — SSH sessions, VS Code Remote, devcontainers, and Docker. The key difference is that the browser can’t auto-open on a headless server, so you need a fixed port and manual URL access.

Remote mode

Set PLANNOTATOR_REMOTE=1 to enable remote mode:

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999  # Choose a port you'll forward

Remote mode changes two behaviors:

1. Fixed port — Uses PLANNOTATOR_PORT (default: 19432) instead of a random port, so you can set up port forwarding once
2. No browser auto-open — Prints the URL to the terminal instead of trying to open a browser

Legacy detection

Plannotator also detects SSH_TTY and SSH_CONNECTION environment variables for automatic remote mode. However, PLANNOTATOR_REMOTE=1 is preferred for explicit control.

VS Code Remote / devcontainers

VS Code automatically forwards ports from remote hosts. When Plannotator starts on a fixed port, VS Code detects it and makes it accessible on your local machine.

1. Set the environment variables in your devcontainer config:

{
  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },
  "forwardPorts": [9999]
}

2. When Plannotator opens, check the VS Code Ports tab — the port should be automatically forwarded
3. Open http://localhost:9999 in your local browser

SSH port forwarding

For direct SSH connections, forward the port in your ~/.ssh/config:

Host your-server
    LocalForward 9999 localhost:9999

Or forward ad-hoc when connecting:

ssh -L 9999:localhost:9999 your-server

Then open http://localhost:9999 locally when Plannotator prints the URL.

Docker (without VS Code)

For standalone Docker containers, expose the port and set environment variables:

ENV PLANNOTATOR_REMOTE=1
ENV PLANNOTATOR_PORT=9999
EXPOSE 9999

Or via docker run:

docker run -e PLANNOTATOR_REMOTE=1 -e PLANNOTATOR_PORT=9999 -p 9999:9999 your-image

Custom browser

The PLANNOTATOR_BROWSER environment variable lets you specify a custom browser or script for opening the UI.

macOS — Set to an app name or path:

export PLANNOTATOR_BROWSER="Google Chrome"
# or
export PLANNOTATOR_BROWSER="/Applications/Firefox.app"

Linux — Set to an executable path:

export PLANNOTATOR_BROWSER="/usr/bin/firefox"

Windows / WSL — Set to an executable:

export PLANNOTATOR_BROWSER="chrome.exe"

You can also point PLANNOTATOR_BROWSER at a custom script that handles URL opening in your specific environment — for example, a script that opens the URL on a different machine or sends a notification with the link.