How to Reach Your Hermes Agent from Phone

Di you fit reach your Hermes agent from phone

To reach your Hermes agent from phone, you go use im web dashboard. The main decision na wetin dey in front of that dashboard. Option one na private mesh network, where dashboard dey listen only on Tailscale address and no port face internet. Option two na public endpoint behind reverse proxy with TLS (transport layer security) and login. That login na the only thing wey dey protect terminal wey enter your server. Option three na SSH (secure shell) from terminal app. E need the least setup, but e give the most access.

This guide start from where running Hermes agent for your own VPS end. You don install the agent, e dey answer for command line, and now you want make e dey your pocket.

The commands below dey use tag v2026.8.3, wey dem publish on 3 August 2026 and label as v0.20.0 for release notes. Hermes dey release often, so pin the machine to one tag instead of following main. The installer accept a commit:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --commit 3c27eb6234bf
hermes version

hermes version show wetin actually dey installed. Compare am with the tag before you trust any flag for this page.

Repository dey ship wetin, and wetin e no ship

No iOS or Android app dey inside Hermes repository. The native client na hermes desktop (alias hermes gui), an Electron application for macOS, Windows and Linux. E fit connect to remote agent instead of local one: set remote URL to http://<server-address>:9119 for Settings under Gateway, or export HERMES_DESKTOP_REMOTE_URL=http://<server-address>:9119 before you launch am. This one solve problem for second laptop. E no do anything for phone.

The interface wey you go use from phone na hermes dashboard, the browser interface. E dey manage configuration, sessions, cron jobs, skills, logs and messaging platforms, and e get terminal inside am: server dey spawn hermes --tui behind PTY (pseudo-terminal) and stream the output go the page. For narrow screen, session switcher dey fold enter slide-over panel, so layout still work for phone.

By default, dashboard dey listen on 127.0.0.1:9119 and e dey open browser tab for the server itself. This one no useful for headless VPS (virtual private server). Start am without the browser and check the socket:

hermes dashboard --no-open
ss -lntp | grep 9119

Listener for 127.0.0.1:9119 fit reachable only from the server. Listener for 0.0.0.0:9119 fit reachable from every network wey the machine connect to, including public network. Na that one line decide how exposed you be, so read am instead of assuming.

Option 1: private mesh with Tailscale

Pick this one unless you get reason not to. Tailscale na mesh VPN (virtual private network) wey dem build on WireGuard. Every device wey you enrol go get stable address and talk directly to the others. Your phone go join the same mesh, so the dashboard no need public port at all.

For the server:

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

Install the Tailscale app for the phone and sign in with the same account. tailscale status for the server go then list the phone by name. Now bind the dashboard to the address wey tailscale ip -4 print:

hermes dashboard --host 100.101.102.103 --port 9119 --no-open

Binding to the mesh address, instead of 0.0.0.0, mean say the listening socket dey only for the Tailscale interface. Port scan of your public IP address no go find anything for 9119 because nothing dey listen there, so your firewall no longer be the only thing wey dey protect you. Confirm am with ss -lntp | grep 9119 again.

The bind address also decide authentication, and na here people dey miss the point. For 127.0.0.1 the dashboard no get login. For any other address, the auth gate na compulsory, and if no provider dey configured, the server go refuse to start. The project call this failing closed. Run am interactively the first time, and e go offer to set username and password immediately. The result dey written to ~/.hermes/.env:

HERMES_DASHBOARD_BASIC_AUTH_USERNAME=you
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH=scrypt$16384$8$1$...
HERMES_DASHBOARD_BASIC_AUTH_SECRET=a-long-random-string

Generate that secret with openssl rand -hex 32 and then leave am alone. E dey sign the session cookie, so changing am go sign every device out. The same file hold your model API keys, so keep am private with chmod 600 ~/.hermes/.env.

Check the gate from another machine for the mesh before you trust am:

curl -s http://100.101.102.103:9119/api/status | jq '.auth_required, .auth_providers'

true followed by ["basic"] mean say the gate dey on and the password provider na the one wey dey answer. The project's own documentation talk clearly about that provider: na for trusted network or VPN dem design am, and e no suitable for dashboard wey dey face public internet. For mesh, na exactly the situation wey you dey.

For HTTPS inside the tailnet, hand the port to Tailscale:

sudo tailscale serve --bg localhost:9119
sudo tailscale serve status

Tailscale terminate TLS with certificate wey dem issue for the machine's MagicDNS name, so browser stop to show warning and the session cookie get its Secure flag. Enable MagicDNS and HTTPS Certificates for the DNS page of the Tailscale admin console first. Read the acknowledgement while you dey there: your machine names and tailnet DNS name dey published to public certificate transparency ledger, and anybody fit read am.

The honest cost here na the coordination server. Traffic between your phone and VPS dey encrypted end to end and e no pass through Tailscale, but the account wey decide which devices belong to the mesh no dey for your hardware. If this one matter to you, run the control plane yourself with Headscale, the Tailscale control server wey you self-host, and point clients to am with tailscale up --login-server https://headscale.example.com. If you prefer drop the mesh and configure peers by hand, the comparison between plain WireGuard and Tailscale explain wetin you give up.

Option 2: public HTTPS endpoint, and the trap wey dey inside am

Sometimes mesh no dey available. Work phone fit no allow you install VPN client. Then reverse proxy go sit in front of the dashboard. Keep the dashboard for loopback, and make Caddy hold the certificate:

hermes.example.com {
  reverse_proxy 127.0.0.1:9119
}

Caddy dey fetch and renew the certificate by itself. E reverse_proxy dey pass WebSocket upgrades through without extra directives, and na this embedded terminal for dashboard need. For nginx, you must add the Upgrade and Connection headers by yourself. How to issue Let's Encrypt certificate with Certbot on nginx explain the TLS part of this work. Tell Hermes the public name wey people go use, so login callbacks go point to the correct host:

dashboard:
  public_url: "https://hermes.example.com"

Now na the trap. Auth gate dey use bind address, e no dey use the address wey request come from. Dashboard wey bind to 127.0.0.1 behind proxy go see loopback, decide say login no need, then serve anybody wey proxy allow pass. Check wetin you actually publish:

curl -s https://hermes.example.com/api/status | jq '.auth_required'

If that output na false, internet dey one URL away from terminal for your server. No exploit dey involved, and nothing for logs go complain. Two fixes dey, and you need at least one. Either put authentication for the proxy, using Authentik as self-hosted single sign-on provider for front through forward auth, or configure the dashboard own OIDC (OpenID Connect) provider:

HERMES_DASHBOARD_OIDC_ISSUER=https://auth.example.com/application/o/hermes/
HERMES_DASHBOARD_OIDC_CLIENT_ID=hermes-dashboard
HERMES_DASHBOARD_OIDC_SCOPES="openid profile email"

Even when you do am correctly, this option get a minimum risk level wey you no fit reduce. Public login page na page anybody fit reach and attack, and shell for your VPS dey behind am. Username and password alone na weak protection for this situation. Na why the docs recommend OAuth or OIDC for public binds. Rate-limit the login, keep ufw closed to everything except the proxy ports and SSH, and check the access log from time to time.

Option 3: SSH and mosh from a mobile terminal

Na route wey require the least work: install terminal app for the phone, load SSH key inside am, then use the agent own text interface.

ssh you@vps.example.com
tmux new -A -s phone
hermes --tui

tmux new -A -s phone dey attach to session wey dem call phone, or e create am if no session dey. This one make the agent continue to run when connection drop, and you go return to the same place next time. Na the same pattern wey dem dey use for control Claude Code from phone.

Plain SSH for mobile network no comfortable, because connection dey die whenever phone change address or enter sleep mode. Mosh solve this problem. E dey run over UDP (user datagram protocol) and e dey synchronize terminal state instead of byte stream. So session fit survive when you move from wifi go cellular:

sudo apt install -y mosh
sudo ufw allow 60000:61000/udp

For the phone, run mosh you@vps.example.com. Mosh start mosh-server through your existing SSH login, then e move the session go UDP for the 60000 to 61000 range. Na why that range must dey open.

The security cost dey straightforward. SSH session na shell, and shell fit do everything wey that account get permission to do. The agent approval prompts na the last thing between stolen unlocked phone and your files. Use dedicated non-root account for this, key only, and work through harden SSH on a VPS before you put key for device wey you dey carry around.

Wetin dey spoil for mobile network

Four things, and none of dem na bug wey configuration fit solve.

Dashboard go log you out while you no dey look. Access tokens get 15 minute TTL (time to live), and current API contract no get refresh token. When token expire, page go see 401 response and navigate back to /login. Open dashboard, put phone for pocket for twenty minutes, and when you come back, you go see login screen; anything wey you dey type don disappear. Nothing spoil. Sign in again.

Embedded terminal no dey survive background tab. Server go spawn TUI (text user interface) behind PTY and cleanly reap am when tab close; when you open am again, e go spawn fresh one. Mobile browsers dey discard background tabs to reclaim memory, so if you switch go another app for long enough, that terminal go end. Your chat history dey safe because sessions dey stored for server, and hermes sessions list still dey show dem. You no fit reattach to the terminal itself. If you need session wey go survive, use tmux over SSH.

Idle connections dey die quietly. Mobile carriers dey drop idle TCP connections to reclaim NAT (network address translation) table entries, and phone almost dey stop servicing network once screen off. WebSocket wey don stay silent for some time usually don already die when you unlock phone, and page go reconnect only after you touch am. Na why mosh dey feel better pass SSH for phone: e never get connection wey e fit lose.

Nothing dey push notification. Dashboard and SSH session no fit wake your phone. No Hermes app dey for the device, so no path dey reach platform push service. Long agent run fit finish, and you go only know the next time you check.

Notification dem dey arrive through messaging gateway

The solution for that last one na the gateway. E dey use another way to reach the agent completely. hermes gateway connects the agent to messaging platforms like Telegram, Discord, Slack, WhatsApp, Signal and email. You fit then talk to your agent inside app wey already get push channel for your phone, already dey handle background delivery, and already dey manage network interruption.

hermes gateway setup
hermes gateway install
hermes gateway status

hermes gateway install registers the gateway as systemd service, so e go return after reboot. Hermes installer no dey create service units for you. So hermes dashboard no go come back by itself after restart. Write unit for every component wey you depend on. how to write systemd services and timers on a VPS explain the file itself.

Scheduled job fit push result the same way, without any conversation:

hermes send -t telegram -s "Backup report" -f /home/you/report.txt

Authorisation for here dey deny by default. If you no set allowlist and GATEWAY_ALLOW_ALL_USERS remain unset, system go refuse every user. Na the correct starting point be that. Put the accounts wey you want inside ~/.hermes/.env:

TELEGRAM_ALLOWED_USERS=123456789
GATEWAY_ALLOWED_USERS=123456789

Or you fit enable code-based pairing instead of pasting numeric IDs, by setting unauthorized_dm_behavior: pair inside ~/.hermes/config.yaml. If unknown account message the agent, e go receive eight character code. Nothing else go happen until you approve am:

hermes pairing list
hermes pairing approve telegram ABC12DEF
hermes pairing revoke telegram 123456789

Codes dey expire after one hour. User fit request one every ten minutes. Five failed attempts go lock that account out.

How to limit the damage from stolen phone

Any phone wey fit reach your agent fit run commands for your server, and phones fit lost. Decide now wetin the person wey hold am fit do.

Keep approvals on. approvals.mode default na smart, wey ask auxiliary model to judge risk and auto-approve only low-risk commands. If you set am to off, e be the same as running everything with --yolo, and HERMES_YOLO_MODE=1 fit do am through the environment. No carry phone wey dey talk to agent for that state. Set approvals.cron_mode: deny so scheduled jobs no fit approve themselves while you dey sleep.

approvals:
  mode: smart
  cron_mode: deny

Give the agent smaller area wey e fit damage. terminal.backend: docker dey run commands inside container wey drop all Linux capabilities except small list, set no-new-privileges, and limit process count. This make the container be the boundary instead of the prompt. terminal.cwd pin the working directory. HERMES_WRITE_SAFE_ROOT restrict write_file and patch to the directories wey you name, and any write outside dem go block without approval fit override am.

export HERMES_WRITE_SAFE_ROOT=/home/you/projects:/home/you/.hermes

Hermes already block writes to ~/.ssh, ~/.aws, ~/.kube and /etc/sudoers. E refuse to write .env files anywhere for disk, and e reject strict list of destructive commands no matter wetin your approval settings talk. Treat this one as minimum protection, no be your full plan. Run the agent as ordinary user, never as root. The same reasoning apply to any coding agent wey you leave running without supervision, and how to run Claude Code safely for VPS explain am in more detail.

Then write down the revocation steps before you need dem. If you remove the device for Tailscale admin console, mesh access go stop immediately. If you change HERMES_DASHBOARD_BASIC_AUTH_SECRET and restart, e go invalidate every dashboard session for every device, because that value dey sign the session cookie. Delete the phone public key from ~/.ssh/authorized_keys to end SSH. hermes pairing revoke telegram <user-id> remove messaging account. If the device get anything wey fit read your provider keys, remove dem with hermes auth logout <provider> and issue new ones upstream.

Check the result instead of assuming say e work. These commands na to run for your own box, and wetin dem print depend on your setup:

tailscale status
hermes pairing list
hermes logs gateway -n 100
hermes status --deep

The logs dey under ~/.hermes/logs/. Read dem after incident, and read dem sometimes even when incident never happen.

FAQ

Hermes get official mobile app for iOS or Android?

No. Hermes repository dey ship command line interface, web dashboard, and Electron desktop client for macOS, Windows and Linux. No first-party iOS or Android build dey. From phone, you fit use web dashboard for browser, SSH client, or messaging platform wey connect through hermes gateway. Third-party mobile clients dey, but na third-party code wey dey hold credentials for your agent, so read the source before you install any.

Why Hermes dashboard dey log me out for my phone?

Access tokens get 15 minute TTL, and the current API contract no get refresh token. When token expire, page receive 401 and navigate go /login. When you put browser for background on phone, this one dey show clearly, because twenty minutes for another app fit make token expire. Set HERMES_DASHBOARD_BASIC_AUTH_SECRET to stable random value so session signing key remain the same across restarts. This remove the second reason wey fit log you out.

I fit put Hermes dashboard for public internet safely?

Only if you use authentication wey you don verify yourself. Auth gate dey switch on based on bind address, so dashboard wey bind to 127.0.0.1 behind reverse proxy no go ask internet for login. Run curl -s https://your-host/api/status | jq '.auth_required' and read wetin e return. Use OAuth or OIDC instead of username and password, because project docs talk say password provider na for trusted networks and VPNs. Private mesh avoid the question completely, na why e better as default.

I need Tailscale account, or I fit self-host the control plane?

You fit self-host am. Headscale na open implementation of Tailscale coordination server, and official Tailscale clients connect to am with tailscale up --login-server https://headscale.example.com. You go then own the list of devices wey fit enter the mesh. The cost be say you now dey run and back up that server, and while e dey down, you no fit enrol or re-authenticate device.

How I fit get notification for my phone when agent finish job?

Use messaging gateway. Dashboard and SSH no get way to wake phone, because no Hermes app dey on the device to receive push notification. Connect agent to Telegram, Signal, Discord, or another supported platform with hermes gateway setup, then allow that platform own app to deliver am. Cron job fit also push one message with hermes send -t telegram -s "Job done" -f /path/to/report.txt, and e go deliver without calling the model.