Last updated: 2026-05-25

Troubleshooting & FAQ

Quick answers to common questions and detailed troubleshooting guides.

Quick FAQ

Q: What is HiTerm?

HiTerm lets you securely access your PC's terminal from your phone, even on subway, coffee shop, or any mobile network.

Q: Is it free?

Yes, HiTerm is completely free. Tailscale's personal plan is also free (up to 100 devices).

Q: Is it secure?

All traffic is encrypted via Tailscale's WireGuard, peer-to-peer, with no third-party relay.

Q: What platforms are supported?

PC: Linux, macOS, Windows (WSL2). Phone: Android 7.0+. iOS is not yet supported.

Q: Do I need mosh and tmux?

Not strictly required, but highly recommended. Without mosh, connections drop on network switches. Without tmux, sessions don't persist.

Q: Do I need to login?

No. Basic SSH works without login. Login unlocks AI notifications and auto IP sync.

Q: Does the connection drop on network switch?

If mosh is installed, no. WiFi โ†” 4G switches seamlessly without dropping.

Q: Will my session be lost?

If tmux is installed, no. Tasks keep running after disconnect and resume on reconnect.

Q: Can I connect to multiple PCs?

Yes. Each hiterm pair adds a new PC to your host list.

Q: How do I uninstall?

rm ~/.local/bin/hiterm && rm -rf ~/.hiterm

Uninstall the Android app directly from the launcher.

Troubleshooting

If the FAQ above didn't solve your problem, the detailed guides below are organized by topic.

First step: Run hiterm doctor โ€” it can automatically detect and fix most issues.

hiterm doctor

Tailscale Issues

"Tailscale required" or "Tailscale not detected"

Check Tailscale status:

tailscale status

If Tailscale is not running:

sudo tailscale up

If tailscale command not found, install Tailscale first. See Tailscale Setup.

Devices can't discover each other

  1. Confirm both devices are logged in to the same Tailscale account
  2. Confirm both show "Connected" in Tailscale
  3. Check the Tailscale admin panel for ACL restrictions (free plan has none by default)

Tailscale IP shows empty

# Check if Tailscale is running
sudo tailscale status

# Get IP explicitly
tailscale ip -4

If no IP is returned, try restarting:

sudo tailscale down && sudo tailscale up

Company/school network blocks Tailscale

Some network environments block Tailscale's WireGuard connections. Try:

  1. Switch to a different network (e.g., phone hotspot) for testing
  2. Contact your network admin about firewall restrictions
  3. Tailscale uses UDP port 41641 โ€” ensure it's not blocked

SSH Issues

sshd not running

macOS:

sudo systemsetup -setremotelogin on

Linux:

sudo systemctl start sshd
sudo systemctl enable sshd

Connection refused

  1. Check sshd is running: sshd -V 2>&1
  2. Check the port: hiterm pair uses port 22 by default
  3. Check firewall rules aren't blocking SSH

Permission denied (publickey)

The phone's public key must be in ~/.ssh/authorized_keys. Re-run hiterm pair to re-add it:

hiterm pair

mosh Issues

mosh not installed

hiterm pair will show the install command. Or install manually:

macOS:

sudo port install mosh    # MacPorts
brew install mosh         # Homebrew

Linux:

sudo apt install mosh     # Debian/Ubuntu
sudo dnf install mosh     # Fedora

mosh connection drops

mosh is designed for unstable networks, but if it drops frequently:

  1. Check Tailscale is still connected
  2. Try reconnecting from the app
  3. Check if your network blocks UDP (mosh uses UDP)

tmux Issues

tmux not installed

macOS:

sudo port install tmux    # MacPorts
brew install tmux         # Homebrew

Linux:

sudo apt install tmux     # Debian/Ubuntu
sudo dnf install tmux     # Fedora

Mouse not working in tmux

hiterm pair automatically configures tmux mouse mode. If it's not working:

# Check if mouse mode is configured
grep "mouse" ~/.tmux.conf

# If missing, add it manually
echo "set -g mouse on" >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

Sessions not persisting

tmux sessions persist as long as the tmux server is running. If sessions disappear:

  1. Check if tmux is installed: tmux -V
  2. Check if the tmux server is running: tmux list-sessions
  3. The session may have been killed (e.g., by exit in the shell)

App (Hi Term) Issues

Can't scan QR code

  1. Confirm PC has run hiterm pair and is displaying a QR code
  2. Confirm the phone camera permission is granted to the app
  3. Confirm the phone has Tailscale installed and connected

Pairing fails

  1. Confirm both devices are on the same Tailscale network
  2. Run hiterm doctor on the PC to check for issues
  3. Try re-running hiterm pair

Connection fails after pairing

  1. Confirm PC sshd is running
  2. Confirm both devices are online in Tailscale
  3. Try hiterm doctor on the PC

Connection failed after network change (IP Change)

If your PC's Tailscale IP has changed and the phone still tries to connect to the old one, HiTerm handles this automatically:

  1. Ensure Tailscale and Hi Term are running on your phone.
  2. Continue working with your AI tools (Claude Code, etc.) on your PC.
  3. The next time an AI tool sends a notification, HiTerm will silently update the IP on your phone in the background.

If you need to force an update immediately: Run hiterm notify test on your PC. This triggers the synchronization process manually.

App not receiving notifications

  1. Run hiterm notify test on the PC
  2. Check that the phone is online in Tailscale
  3. Run hiterm doctor to verify notification hooks are installed

Notification Issues

Notifications not arriving

# Test notifications
hiterm notify test

# Check hook status
hiterm notify

# Run doctor to fix hooks
hiterm doctor

AI tool hooks not working

Hooks are installed automatically by hiterm pair and managed by hiterm doctor. If they're not working:

# Reinstall hooks
hiterm doctor

Manual hook configuration for unsupported tools:

# Get the hiterm binary path
which hiterm

# The hook command format:
<hiterm-path> notify hook --tool=<name> --event=<event>

See Command Reference: notify hook for configuration examples.

Update Issues

Update fails

# Try with explicit source
hiterm update --source=hono

# Or skip verification
hiterm update --skip-verify

Binary not found after update

The update replaces the binary in place. If it's not found:

# Check where it should be
which hiterm

# If not in PATH, add it
export PATH="$HOME/.local/bin:$PATH"

WSL2 Issues

Tailscale not working in WSL2

WSL2 has its own network namespace. Two approaches:

Option A: Install Tailscale on Windows (Recommended)

  1. Install Tailscale on Windows (not inside WSL2)
  2. WSL2 automatically gets network access through the Windows host
  3. Use the Windows Tailscale IP for hiterm

Option B: Install Tailscale inside WSL2

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

This works but may have issues with DNS and network bridging.

hiterm pair times out in WSL2

If the phone can't reach the WSL2 IP:

  1. Check that Tailscale is running on the Windows host (not inside WSL2)
  2. Use the Windows Tailscale IP, not the WSL2 internal IP
  3. The phone must be on the same Tailscale network as the Windows host

mosh not available in WSL2

sudo apt install mosh

If mosh fails to connect, the issue is likely Tailscale networking. See above.

Still Stuck?

Run diagnostics and check the output:

hiterm doctor

If the issue persists, contact support:

Related Docs