​

Headmaster on the Go

​

How browser access works

​

Desktop-bundled WebUI

​

Running it locally

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

​

LAN access

1. In the WebUI settings, also turn on Allow LAN access.
2. The panel shows two URLs:
   • Local: http://localhost:25808
   • Network: http://192.168.x.x:25808
3. 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

​

Starting WebUI from the command line

​

Desktop-bundled

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

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

• 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

​

Server with public IP (public IP)

1. Create a systemd service:

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

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

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

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

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

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

2. Start:

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

3. Open port 25808 in System Settings → Network → Firewall.

• 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

1. Strong passwords: Use a complex admin password. The initial random password is strong — keep it or change it to something equally strong.
2. Firewall: Only expose port 25808 to the networks that need it. Use Tailscale instead of opening the port to the whole internet.
3. 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.
4. Rate limiting: The login screen is already rate-limited, but a reverse proxy can add additional protection.
5. 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 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.

​

Android via Termux

# 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

​

Password management