The complete guide.

Console is the Android app that connects directly to the Hermes Agent running on your server, PC or VPS. It talks to Hermes' own Gateway and Dashboard; nothing else needs installing.

1. Install Console on your phone (you need version 1.2.15 or newer).
2. Paste one line on the machine where Hermes lives. It gets Hermes ready for the app and shows a code.
3. Scan the code with the app. You are connected.

The code carries the machine's address, its key and the Dashboard sign-in, so you type nothing. You do not need to know whether the ports are ready or hunt for keys either.

If your case is different (you already set it up, you do not know the Dashboard password, you come from an older install, you use Docker), jump to its section.

From Google Play, with Obtainium or with the APK from the GitHub releases. You need Android 7 or later and Console 1.2.15 or newer.

Pick one path and stay on it: Google Play and GitHub/Obtainium sign the app differently, and Android will not update from one to the other. Install only officially published builds.

When you open Console you will see “Connect to your Hermes” and a “Scan code” button. Leave it there and go to step 2.

Paste the line for your system on the machine where Hermes lives: a VPS, a homelab, a mini-PC or your own computer, running Linux, macOS or Windows. Everything happens in the window you paste it into; no other window opens and the services keep running in the background with no window of their own.

• Mac and Linux: in a Terminal.
• Windows: in Windows PowerShell 5.1 or newer opened as administrator. The installer adds one firewall rule limited to your private network and never asks for elevation by itself.
• Windows with WSL2: use the Windows line too, in Windows PowerShell and outside WSL, so networking, firewall and startup are set up correctly.

You will see the xPetaLab | CONSOLE seal and seven numbered steps, 1/7 to 7/7: Looking at this computer, Checking Hermes, Preparing the services, Starting Hermes in the background, Setting up the Dashboard sign-in, Checking that your phone can reach it and Making your code. If Hermes was not installed, it installs it. If it was, your keys and sign-ins are kept: you can repeat the line as often as you like.

The first time, the Dashboard takes a while to build; on a slow machine it can take several minutes. Wait: the installer keeps working and does not report a false failure.

Only when everything has been checked for real, through the address your phone will use, does SCAN THIS CODE WITH CONSOLE appear with the code. The last lines say it too: Needs Console 1.2.15 or newer on the phone.

If Hermes has no AI model yet, pick your provider and model from the Dashboard, inside the app.

1. Leave the code visible on the machine's screen.
2. On your phone, in Console, tap “Scan code” and point it at the code. The camera is only asked for on that screen.
3. Console tells you in plain words what it is about to connect to and checks the address, the chat key and the Dashboard sign-in before saving anything. Confirm.
4. You will see “Connected”. You can now talk to Hermes.

No camera at hand, or the code is on the phone itself? The installer also prints a link that starts with hermes://pair: copy it and use “I have a link” in the app.

The code and the link carry your Hermes key and the Dashboard sign-in. Treat them like a password: do not share them or publish screenshots.

If the installer created a Dashboard password itself, it also shows it once, in case you want to open the Dashboard in a browser.

If you already ran the setup and only need the code (for another phone, or because you closed it), this line shows it again without reinstalling or restarting anything: it changes nothing on disk.

It first rechecks the Gateway and the Dashboard through the address your phone uses. If one is down or does not accept the sign-in, it shows no code and asks you to repeat the full setup (step 2). On Windows and WSL2, again in Windows PowerShell and outside WSL.

In the app, the “I don't have a code” help (“Get the code on your computer”) has these same lines ready to copy or send to the computer, with an “I already set up this computer” button for this case.

Console asks for it when the Dashboard already had a password the installer does not know (it never changes one on its own). If you do not remember it, it cannot be read back: you make a new one.

This line creates a new Dashboard sign-in, ends the sessions opened with the old one (also a phone or browser you want to cut off) and shows a new code. Scan it as in step 3. On Windows it runs in PowerShell, like the setup.

If the password is written by hand in Hermes' .env file (HERMES_DASHBOARD_BASIC_AUTH_*), that file wins and the command does not edit it: it says so and shows the code with the sign-in that is there. On a Unix machine without systemd or launchd, stop the two services first; the message names the two commands.

Up to Console 1.2.14, the setup installed a third service, the Mobile Bridge (port 9131). Console 1.2.15 and newer no longer use it: they talk directly to Hermes' Gateway and Dashboard, and a new setup neither installs nor downloads it.

• Update the app. A Console older than 1.2.15 needs the bridge, which a new install no longer brings: put 1.2.15 or newer on the phone. On the first launch after updating, Console checks each connection once, deletes the bridge data it kept and tells you if a connection needs a Dashboard sign-in.
• Repeating the setup line breaks nothing. It sets up the Gateway and the Dashboard, and if the bridge is still running it leaves it running, untouched, so a phone with an older Console keeps connecting. At the end it shows you the cleanup line.
• Once all your phones have 1.2.15 or newer, run this line: it stops and removes the bridge and nothing else (the Gateway and the Dashboard are not touched). Running it twice, or on a machine that never had one, says there is nothing to remove and changes nothing.

It removes the bridge's service, its process and its files. Its backups and logs are yours and stay. If you opened port 9131 in the firewall, you can close it now: nothing listens there any more.

If you cannot or do not want to use the installer, choose “Connect manually” on Console's first screen and fill in what the connection asks for:

• Gateway address: the machine's address, reachable from your phone, preferably over HTTPS (for example the Tailscale one or your network's).
• Gateway key: the API_SERVER_KEY of that Hermes. It is not any AI provider's key: do not paste an OpenAI or similar one here.
• Dashboard address: optional; by default it is port 9119 of the same machine.
• Dashboard sign-in: you sign in with that Dashboard's username and password.

The “Check connection” button on the connection's screen probes the Gateway and the Dashboard and tells you which of the two does not answer.

Set the machine up by hand

This is what the installer does, by hand. On the machine where Hermes lives, add the Dashboard sign-in to Hermes' .env file (~/.hermes/.env on Linux and macOS):

HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=your-new-password

and start it open to your network: hermes dashboard --no-open --host 0.0.0.0 --port 9119. For the Gateway, make a long key (openssl rand -hex 32; Hermes refuses a short one) and add to the same .env:

API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=paste-the-key-here

and start it with hermes gateway. Then, on the phone, “Connect manually”.

WSL2: the Windows line runs in Windows PowerShell, outside WSL, as in step 2.

Docker or another container: the setup line is meant for the machine where Hermes is installed directly (if it does not find Hermes, it installs it), so it is not for a Hermes that lives inside a container. Console only needs the Gateway (port 8642 by default, with its key) and the Dashboard (port 9119 by default, with its username and password) to be reachable from your phone: publish those two ports from the container, preferably inside a private network or over HTTPS, and use Connect by hand.

With the official nousresearch/hermes-agent image, one container serves both. Create a folder with this docker-compose.yml:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"   # Gateway
      - "9119:9119"   # Dashboard
    volumes:
      - ./hermes-data:/opt/data
    environment:
      HERMES_DASHBOARD: "1"
      HERMES_DASHBOARD_BASIC_AUTH_USERNAME: admin
      HERMES_DASHBOARD_BASIC_AUTH_PASSWORD: ${DASHBOARD_PASSWORD}
      API_SERVER_ENABLED: "true"
      API_SERVER_HOST: 0.0.0.0
      API_SERVER_KEY: ${GATEWAY_KEY}

Create the two secrets next to it and start it:

printf 'GATEWAY_KEY=%s\nDASHBOARD_PASSWORD=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 16)" > .env
docker compose up -d

Then, on the phone, “Connect manually”: address http://HOST-IP:8642, the value of GATEWAY_KEY as the key, and for the Dashboard the user admin with the value of DASHBOARD_PASSWORD (both are in the .env file). The Dashboard demands a username and password as soon as it listens beyond the machine itself; without them it does not start. restart: unless-stopped brings both back by themselves after the container or the machine restarts.

Unraid: create the container with that same image, the same command (gateway run), ports 8642 and 9119, a path for /opt/data and the same variables as container fields.

Do not open these ports to the Internet without valid HTTPS and a suitable network policy.

• Chat — token-by-token streaming, selectable text and code blocks, image and document attachments with visible progress, and image generation right in the conversation.
• Voice — choose per instance between the phone engine and Hermes server; dictation, read aloud, and manual conversation remain available with optional continuity. Voice guide →
• Sessions — every conversation of your agent, including the ones you started on desktop.
• Kanban — the agent's task board: backlog, in progress, review, and blocked; its results can notify you and open the related work.
• Models — switch the active model, Ollama catalog, and external providers (LM Studio, OpenAI-compatible).
• MoA — Mixture-of-Agents recipes editable from the app: several models propose, one aggregates the final answer.
• SSH terminal — a real shell with a PTY against any machine, plus an SFTP browser to move files.
• Cron — scheduled jobs: create, edit, pause, trigger manually, and receive a notification that opens the right run.
• Memory — read and edit the agent's persistent memory, with local drafts.
• SOUL — the agent's identity document (its persona), editable with templates and autosave.
• Skills — browse the skills installed on your agent.
• Task Center — every run launched from the app, with live tracking.
• Approvals — when the agent wants to run something sensitive, it arrives with its risk level: approve or reject, right from the notification.
• Bots with faces — each profile picks a pet, an image or a face, and you can see how it is doing (working, free).

• Appearance — dark and light themes (including pure OLED), text size and a font picker.
• Language — Spanish and English, or follow the system.
• Security — app lock with biometrics or PIN; the API key lives encrypted in the Android Keystore.
• Notifications — approvals and terminal Cron/Kanban results, deduplicated and linked to their conversation or run: zero Google, zero third-party push.
• Voice — choose “On this phone” or “Hermes server” per instance; conversation mode can be disabled without losing dictation or read aloud. Set up voice →
• Accessibility — consistent switches, collapsible technical details, and selectors that adapt to large text and narrow screens.
• Server — from the app itself: update Hermes and restart the Gateway.

• Camera — opens only when you scan a code or take a photo attachment. The code is processed on-device; the photo goes to your Hermes only when you send the message.
• Microphone — starts after you begin dictation or a conversation. Keeping a conversation active outside the app requires a separate opt-in and a persistent notification with controls.
• Notifications — local alerts for approvals, runs, and Cron/Kanban, plus controls for Voice or Read Aloud that you started. No third-party push is used.
• Biometrics — only for optional App Lock. Android performs the check; Console does not access biometric templates.
• Photos and documents — selected through Android's pickers. On modern Android, the app does not enumerate or import general storage.

The Google Play variant is remote-only and does not include the permissions or app queries used by the full variant for F-Droid integration.

• "Can't connect". Check phone and server share a network (Tailscale up on both?) and the port is 8642. You can paste the setup line for your system again: it is safe, keeps your keys, and repairs or starts the required services.
• “Your phone cannot reach the computer”. Use the same Wi-Fi or turn on Tailscale on both and retry.
• “Hermes rejected this key”. The key changed: get a new code on the computer with show the code again.
• Windows blocks the connection. Paste the line again in a PowerShell opened as administrator: that lets it create the private-network-only firewall rule. If the LAN is marked “Public”, switch it to “Private” or use Tailscale.
• TLS certificate error. On a private network connect over LAN or Tailscale (internal HTTP is fine there); for a public domain use a valid certificate on the proxy.
• The code was closed or does not appear. Use “show the code again” and choose the system of the machine running Hermes. If none appears, repeat the setup (step 2): the message says which service is failing.
• Console asks for the Dashboard password. If you do not remember it, see “I don't know the Dashboard password”.
• No notifications. Enable background listening in Settings → Notifications and grant the notification permission (Android 13+).

• Connect over LAN or Tailscale whenever you can; don't open 8642 or 9119 to the public internet.
• If you need access from outside, Tailscale gives you an encrypted private network with no open ports; HTTPS with a valid certificate is the alternative.
• Your API key never leaves the phone except towards your server, and is stored encrypted in the Keystore.
• The dashboard is password-protected from first boot (the installer makes sure of it).
• Messages and attachments go to the Hermes you configure; XPeta Lab operates no backend, account, or tracking. Optional providers and the on-device ZXing QR scanner are covered in the full privacy policy →