Headmaster on the Go

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

How browser access works

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

Both modes share the same UI. They intentionally do not share state by default — the standalone mode has its own data directory. To share data, point standalone at the desktop's directory with --data-dir.

Desktop-bundled WebUI

This is the quickest way to get browser access. The WebUI runs alongside the desktop app and shares the same data — conversations, memory, skills, channels, sessions.

WebUI settings panel with QR code

Screenshot placeholder: The Headmaster on the Go settings panel showing the URL and QR code.

Running it locally

Open Headmaster.
Open Settings → Headmaster on the Go.
Turn on Enable browser access.
The panel shows a URL (e.g., http://localhost:25808).
Open that URL in a browser on the same machine.
Copy the initial random admin password immediately — the UI masks it after first display.

LAN access

In the WebUI settings, also turn on Allow LAN access.
The panel shows two URLs:
- Local: http://localhost:25808
- Network: http://192.168.x.x:25808
Open the Network URL from another device on the same Wi-Fi.

Only enable LAN access on networks you trust. The login screen is bcrypt-hashed and rate-limited, but any device on your LAN can reach it.

QR code login

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

Starting WebUI from the command line

Desktop-bundled

| 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.

Standalone

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

headmaster-web resetpass            # reset admin password

Cross-network access (3 methods)

Tailscale (recommended) (recommended — easiest)

Difficulty: Very easy. No public IP needed.

Install Tailscale on the Headmaster computer. Log in.
Get the Tailscale IP: tailscale ip (format 100.x.x.x).
Enable Allow LAN access in WebUI settings (or start with --remote).
Install Tailscale on your remote device (phone, laptop). Log in with the same account.
Open http://100.x.x.x:25808 in the remote device's browser.
Log in via QR code scan (recommended) or username (admin) + password.

Troubleshooting:

Can't connect? Ensure both devices use the same Tailscale account, client is running, firewall allows traffic. Restart: sudo tailscale restart.
Can't access Headmaster? Confirm --remote flag is used, check IP with tailscale ip, ensure port 25808 is free.
Check status: tailscale status.

ZeroTier

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

Server with public IP (public IP)

Difficulty: Medium. Requires a cloud server with public IP (Linux Ubuntu recommended).

Linux server deployment:

Create a systemd service:

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

Add configuration:

[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

Enable and start:

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

Open the firewall:

# Ubuntu/Debian (ufw)
sudo ufw allow 25808/tcp
sudo ufw reload

# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=25808/tcp
sudo firewall-cmd --reload

Access: http://Your-Server-IP:25808

macOS server deployment:

Create a LaunchAgent at ~/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>

Start:

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

Open port 25808 in System Settings → Network → Firewall.

Troubleshooting:

Service won't start? Check Headmaster path (which Headmaster), user permissions, logs (sudo journalctl -u headmaster-webui.service -n 50).
No internet access? Verify firewall and cloud security groups allow port 25808. Ensure --remote flag is used.
Check port: telnet Your-Server-IP 25808 or nc -zv Your-Server-IP 25808.

Security recommendations

Strong passwords: Use a complex admin password. The initial random password is strong — keep it or change it to something equally strong.
Firewall: Only expose port 25808 to the networks that need it. Use Tailscale instead of opening the port to the whole internet.
HTTPS: For production deployments, put a reverse proxy (nginx, Caddy) in front with TLS termination. Don't expose the raw port over the public internet without encryption.
Rate limiting: The login screen is already rate-limited, but a reverse proxy can add additional protection.
Single user: WebUI currently supports a single user (admin). Multiple people can access using the same admin account, but separate user accounts are not supported yet.

Mobile access

The WebUI is mobile-responsive. On a phone browser:

The sidebar collapses into a hamburger menu.
The composer sticks to the bottom.
File previews open in a full-screen overlay.
Approvals and clarifications render as tappable cards.

This is the v1 mobile experience. A native mobile app is planned for v2.

Android via Termux

Only WebUI mode works on Android (the desktop window needs an X server). Community-supported.

Requirements: Android 7.0+, ~5 GB free storage, Termux from F-Droid (Play Store build is outdated).

# 1. Install Proot Ubuntu
pkg update -y
pkg install proot
pkg install git wget

# 2. Install Headmaster in Proot environment
# (follow the community guide for the latest install steps)

# 3. Start WebUI
Headmaster --no-sandbox --webui --remote

Access from your phone's browser at http://localhost:25808 or http://<device-ip>:25808 from another device on the same network.

Password management

| Mode | Command | Notes | |---|---|---| | Desktop-bundled | Headmaster --resetpass | Resets the admin password | | Standalone (tarball) | headmaster-web resetpass | Resets the admin password | | Standalone (in-repo dev) | bun run resetpass | Resets the admin password |

The initial password is shown once when you first enable WebUI. Copy it immediately. If you miss it, use resetpass to generate a new one.