> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcaplabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Headmaster on the Go

> The initial password is shown once when you first enable WebUI. Copy it immediately. If you miss it, use `resetpass` to 

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

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

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

```bash theme={null}
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.

1. Install [Tailscale](https://tailscale.com/) 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.

**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:**

1. Create a systemd service:

```bash theme={null}
sudo nano /etc/systemd/system/headmaster-webui.service
```

2. Add configuration:

```ini theme={null}
[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:

```bash theme={null}
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:

```bash theme={null}
# 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`

**macOS server deployment:**

1. Create a LaunchAgent at `~/Library/LaunchAgents/com.headmaster.webui.plist`:

```xml theme={null}
<?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:

```bash theme={null}
launchctl load ~/Library/LaunchAgents/com.headmaster.webui.plist
launchctl start com.headmaster.webui
```

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

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

```bash theme={null}
# 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.