Headmaster on the Go

Headmaster on the Go is the browser-based interface. It lets you access your agents from a phone, tablet, or another computer — without installing the desktop app on that device.

Two modes

Mode	Entry point	Data directory	When to use
Desktop-bundled	Toggle in Settings, or `Headmaster --webui`	Same as desktop	Phone on the same network, second screen, testing. Shares all data with the desktop app.
Standalone	`headmaster-web` CLI on a headless server	Separate directory	Headless server, container, always-on deployment. No desktop install needed.

Both modes share the same UI. To share data between them, point standalone at the desktop’s directory with --data-dir.

Desktop-bundled WebUI

Open browser access settings

Go to Settings → Headmaster on the Go.

Enable browser access

Turn on Enable browser access. A URL appears (e.g., http://localhost:25808).

Copy the admin password

The panel shows a random initial password — copy it immediately. The UI masks it after first display. If you miss it, use resetpass to generate a new one.

Open in browser

Open that URL in a browser on the same machine.

LAN access (same Wi-Fi)

Enable LAN access

In WebUI settings, turn on Allow LAN access. The panel shows two URLs: a local one and a network one (http://192.168.x.x:25808).

Open from another device

Open the Network URL from your phone or another device on the same Wi-Fi.

Only enable LAN access on networks you trust. Any device on your LAN can reach the login screen.

When WebUI is enabled, the desktop app shows a QR code. Scan it with your phone’s camera to open the URL and log in automatically — it encodes the URL and a one-time login token.

Standalone CLI

headmaster-web                      # default port
headmaster-web --remote             # LAN-accessible
headmaster-web --port 8080          # custom port
headmaster-web --data-dir /path     # custom data directory

headmaster-web resetpass            # reset admin password

Command-line flags

Platform	Local access	LAN access
Windows	`Headmaster.exe --webui`	`Headmaster.exe --webui --remote`
macOS	`/Applications/Headmaster.app/Contents/MacOS/Headmaster --webui`	`... --webui --remote`
Linux (user)	`Headmaster --webui`	`Headmaster --webui --remote`
Linux (root)	`sudo Headmaster --webui --no-sandbox`	`sudo Headmaster --webui --remote --no-sandbox`
Android (Termux)	`Headmaster --no-sandbox --webui`	`Headmaster --no-sandbox --webui --remote`

--no-sandbox is required when running as root or inside Proot/Termux. Desktop users should not add this flag.

Cross-network access

Tailscale (recommended — easiest)

No public IP needed. Works across any network.

Install Tailscale on the Headmaster machine

Get the Tailscale IP

Run tailscale ip — you’ll get a 100.x.x.x address.

Enable LAN access

Turn on Allow LAN access in WebUI settings (or start with --remote).

Install Tailscale on your remote device

Access

Open http://100.x.x.x:25808 in the remote device’s browser.

Troubleshooting: Ensure both devices use the same Tailscale account, the client is running, and your firewall allows traffic. Check status with tailscale status.

ZeroTier

Same concept as Tailscale — install on both machines, join the same ZeroTier network, access via the ZeroTier IP.

Server with public IP

Requires a cloud server. Recommended for always-on deployments.Linux (systemd):

sudo nano /etc/systemd/system/headmaster-webui.service

[Unit]
Description=Headmaster WebUI Service
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/usr/bin/Headmaster --webui --remote
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable headmaster-webui.service
sudo systemctl start headmaster-webui.service

Open the firewall:

# Ubuntu/Debian
sudo ufw allow 25808/tcp && sudo ufw reload

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=25808/tcp && sudo firewall-cmd --reload

Access at http://Your-Server-IP:25808.macOS (LaunchAgent):Create ~/Library/LaunchAgents/com.headmaster.webui.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.headmaster.webui</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/Headmaster.app/Contents/MacOS/Headmaster</string>
    <string>--webui</string>
    <string>--remote</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.headmaster.webui.plist

Android via Termux

Only WebUI mode works on Android (the desktop window requires an X server). Community-supported. Requirements: Android 7.0+, ~5 GB free storage, Termux from F-Droid (Play Store build is outdated).

pkg update -y && pkg install proot git wget

# Install Proot Ubuntu, then Headmaster inside it
# See the community guide for the latest steps

Headmaster --no-sandbox --webui --remote

Access from your phone’s browser at http://localhost:25808.

Security recommendations

Strong password — the initial random password is strong; keep it or replace it with something equally long.
Firewall — expose port 25808 only to networks that need it. Tailscale is safer than opening the port to the public internet.
HTTPS — for production deployments, put nginx or Caddy in front with TLS. Don’t expose the raw port over the internet without encryption.
Single user — WebUI supports one admin account. Multiple people can share it, but separate user accounts are not yet supported.

Password reset

Mode	Command
Desktop-bundled	`Headmaster --resetpass`
Standalone (tarball)	`headmaster-web resetpass`
Standalone (in-repo dev)	`bun run resetpass`

Channels

Use Telegram or other messaging apps to reach Headmaster from your phone without a browser.

Runtime settings

Connect your desktop app to a remote runtime.

Getting Started

Core Concepts

HeadmasterUI Settings

Runtime Settings

Features

Security & Privacy

Maintenance

Reference

Headmaster on the Go

Headmaster on the Go

Two modes

Desktop-bundled WebUI

LAN access (same Wi-Fi)

Standalone CLI

Command-line flags

Cross-network access

Android via Termux

Security recommendations

Password reset

Channels

Runtime settings

​Headmaster on the Go

​Two modes

​Desktop-bundled WebUI

​LAN access (same Wi-Fi)

​QR code login

​Standalone CLI

​Command-line flags

​Cross-network access

​Android via Termux

​Security recommendations

​Password reset

Channels

Runtime settings

Headmaster on the Go

Two modes

Desktop-bundled WebUI

LAN access (same Wi-Fi)

QR code login

Standalone CLI

Command-line flags

Cross-network access

Android via Termux

Security recommendations

Password reset