Skip to content
← Back to Docs

Host Mode

Host mode runs on your main development machine where your AI coding CLI is installed. It manages CLI sessions and shares them with connected client devices.

What is Host Mode?

In host mode, MobileCLI:

  • Launches and manages AI coding CLI processes (Claude Code, Gemini CLI, Codex, OpenCode)
  • Runs a WebSocket server for client connections
  • Stores local session metadata and bounded scrollback
  • Syncs session state to all connected clients in real-time
  • Works seamlessly with Tailscale for secure remote access

Setting Up Host Mode

1. Select Host Mode

Run mobilecli setup to configure host mode. If you've already completed setup, run mobilecli setup again or use mobilecli pair to add a mobile client.

2. Configure CLI Paths

MobileCLI auto-detects installed CLIs. Verify the paths are correct:

# Default locations
Claude Code: ~/.claude/local/claude
Gemini CLI: ~/.local/bin/gemini
Codex: ~/.local/bin/codex
OpenCode: ~/.local/bin/opencode

3. Start the WebSocket Server

The WebSocket server starts when you run mobilecli or mobilecli setup. By default, it listens on port 9847.

Local Network: ws://[your-local-ip]:9847

Connecting Clients

There are two ways to connect client devices to your host:

QR Code Pairing

The fastest method. Run mobilecli pair to display a QR code, then scan it with your mobile device.

Recommended

Manual Connection

Use mobilecli pair and enter the WebSocket URL, credential id, server id, and pairing token manually in the client app settings.

Security

Host mode uses auth-v2 pairing plus conservative network exposure:

  • Network access: Keep port 9847 reachable only from a trusted LAN, Tailnet, firewall allowlist, or protected custom endpoint.
  • Pairing credential: QR pairing carries the daemon URL, device id/name, credential id, server id, and a one-time pairing token. The daemon stores only a derived verifier.
  • Handshake: The mobile app completes challenge-response auth before sessions, terminal output, filesystem data, or push-token registration are available.
  • Transport: Session data follows the network path you configure. Use Tailscale or your own TLS endpoint for untrusted networks.

Managing Sessions

From the host, you can:

  • Create new sessions with different CLIs and working directories
  • View all active and archived sessions
  • Send input to any session (even from connected clients)
  • Monitor real-time output from CLI processes
  • Terminate sessions when done
← Getting Started Client Mode →