Setup guide

Get started

One command on the computer that runs Hermes, then a QR code scan on your phone. Plan on about five minutes.

  1. Before you begin

    • Hermes Agent installed and working on your Mac, Linux or Windows computer. If you haven't set it up yet, follow the Hermes Agent docs first.
    • To use it away from home (recommended): install Tailscale on both the computer and your phone, and sign in to the same account on both. The personal plan is free.
    • Without Tailscale, the phone can reach Hermes on the same Wi-Fi, through a relay you host (no app on the phone, no open ports at home), or through your own HTTPS URL. See networking options.

  2. Run the installer on your computer

    Open a terminal on the computer running Hermes and paste the command for your system.

    In Terminal:

    curl -fsSL https://raw.githubusercontent.com/michaeldimuro/hermes-mobile/main/install/install.sh | bash

    The dashboard runs as a launchd agent, and the installer builds ~/Applications/Hermes.app (see step 2).

    What the installer does

    • Installs the hermes-mobile plugin into Hermes.
    • Runs the Hermes dashboard as a service that starts at boot (launchd on macOS, a systemd user service on Linux, a logon Scheduled Task on Windows), protected by a generated password.
    • Makes it reachable from your phone: Tailscale Serve (HTTPS) by default when Tailscale is installed, otherwise your local network.
    • Sets up the push-notification relay.
    • On macOS, builds ~/Applications/Hermes.app.
    • Prints your connection details and opens your pairing page.

    It is safe to run again at any time; re-running upgrades everything in place. --uninstall removes everything it added.

    Options

    On macOS and Linux, pass flags after bash -s --:

    curl -fsSL https://raw.githubusercontent.com/michaeldimuro/hermes-mobile/main/install/install.sh | bash -s -- --voice --onepassword

    On Windows, set environment variables first, in the same PowerShell window:

    $env:HERMES_MOBILE_NETWORK="lan"
irm https://raw.githubusercontent.com/michaeldimuro/hermes-mobile/main/install/install.ps1 | iex
    macOS / Linux flagWindows variableWhat it does
    --network tailscale
    --network lan
    --network relay
    --network https://your.url    		 HERMES_MOBILE_NETWORK How the phone reaches Hermes.
    --relay-url https://relay.example.com
    --relay-token <secret>    		 HERMES_MOBILE_RELAY_URL
    HERMES_MOBILE_RELAY_TOKEN    		 With relay: your self-hosted relay and its secret. No VPN on the phone and no open ports at home. Run your own relay.
    --voice HERMES_MOBILE_VOICE=1 Set up ElevenLabs voice for every bot. Needs ELEVENLABS_API_KEY in ~/.hermes/.env.
    --onepassword HERMES_MOBILE_ONEPASSWORD=1 Give every bot headless 1Password access with a service-account token. You'll be asked to paste it; the input is hidden.
    --real-browser <bot> HERMES_MOBILE_REAL_BROWSER=<bot> Let that bot use a copy of your real Chrome profile in a visible window, for Google SSO and similar. Opt-in: it shares your cookies with that bot.
    --no-push HERMES_MOBILE_PUSH=0 Skip the notification relay.
    --pair HERMES_MOBILE_PAIR=1 Only show the pairing page again.
    --uninstall HERMES_MOBILE_UNINSTALL=1 Remove everything the installer added.

  3. macOS only: grant Full Disk Access

    Scripts your bots run otherwise trigger prompts like "python3 would like to access data from other apps", and nobody is there to click Allow while you're away. The installer's Hermes.app launcher runs Hermes, so granting it access once covers everything Hermes starts.

    1. Open System Settings → Privacy & Security → Full Disk Access.
    2. Click +, then go to your home folder → Applications → Hermes, and click Open.
    3. Make sure the switch next to Hermes is on.

    Coming back after a reboot, unattended. Hermes starts when you log in. If the Mac must recover from a power cut or update with nobody at the keyboard, turn on automatic login, which requires FileVault to be off. That's a real trade-off: anyone with physical access to the Mac gets in and the disk isn't encrypted. Only do it if the Mac is somewhere you trust.

    Full Disk Access means anything Hermes runs can read your files. See Security.

  4. Install the app

    iPhone

    TestFlight and App Store Coming soon

    A public download isn't available yet. This section will link to it when it is.

    For now, build it yourself with a free Expo account: build Hermes Mobile yourself.

    Android

    Build it yourself with the same guide: build Hermes Mobile yourself.

  5. Pair your phone

    At the end of the install, your pairing page opens in the computer's browser with a QR code. Scan it with your phone's Camera app and Hermes Mobile opens, already connected.

    Prefer typing? Open the app's Connect screen and enter the URL, username and password the installer printed.

    Need the pairing page again later? Re-run the installer with --pair (Windows: HERMES_MOBILE_PAIR=1).

  6. Optional extras

    • Voice mode: add ELEVENLABS_API_KEY=... to ~/.hermes/.env, re-run the installer with --voice, then choose each bot's voice in the app.
    • Screen share for sign-ins: works automatically once the plugin is installed. For Google sign-ins, re-run with --real-browser <bot> for the bot that needs it.
    • 1Password: re-run with --onepassword and paste a service-account token so every bot can read secrets without prompts.
    • Push notifications: turn them on in the app under Settings → Notifications.

    Something not working? See Troubleshooting.