DockerFull install guide

$ docker run -d --name hermes-relay --network host -v ~/.hermes:/home/relay/.hermes:ro hermes-relay

Support

Updated9 hours ago

LanguageKotlin

Setup difficultyAdvanced

MobileNative app

ThemeDark mode

Stars: 401
Ports: 8767 (Relay server WebSocket/HTTP listener), 9443 (Hermes Secure Link (optional pinned TLS ingress))
Requires: Hermes Agent (upstream), Python

Hermes-Relay conversation voice controls in chat

Hermes-Relay native Git workspace with changes, inline diff, and staging controls

Hermes-Relay CLI UI settings and CUA driver

What is Hermes-Relay?

Hermes-Relay links your self-hosted Hermes AI agent to Android phones and desktop computers. The Android app provides streaming chat, hands-free voice, and complete agent management — models, keys, skills, and profiles — in a native mobile interface. An optional plugin adds terminal access, notifications, desktop tools, enhanced voice, and device control (sideload builds only). The desktop CLI (Windows, macOS, Linux) lets Hermes run commands, read files, and access the screen on paired machines with explicit consent. Connections are direct and local-first; Tailscale is the recommended way to reach your agent from anywhere. The relay server is a small Python service you can run via Docker, systemd, or manually. Requires a Hermes agent with Dashboard/Gateway enabled. Licensed MIT.

Should you self-host Hermes-Relay?

Hermes-Relay scores 53/100 on selfhost.directory (how scoring works) and ranks #26 of 120 in AI Assistant. It has 401 GitHub stars.

It shipped 7 stable releases in the past year. The latest, android-v1.19.0, came out on 20 October 2026. New versions land roughly every 5 days.

Setup is advanced: plan for several services and some ongoing maintenance. It is MIT-licensed and written mostly in Kotlin.

Its closest alternative on selfhost.directory is hermes-agent (89/100, 257 957 stars). It scores higher overall, so compare the two before you pick. See Hermes-Relay vs hermes-agent side by side.

Features

Device Control (sideload only)Sideload APK + paired Relay plugin required
Git workspaceRequires Relay plugin
Media enhancementsRequires Relay plugin
Notifications companionRequires Relay plugin
Remote access via TailscaleRecommended path
Secure Link (pinned TLS)Advanced option, requires Relay plugin
Session History
Terminal/TUI accessRequires Relay plugin
Voice Conversations

How to configure Hermes-Relay

RELAY_ALLOW_INSECURE_API_BEARER0Dev-only escape hatch for non-loopback plaintext Hermes API bearer auth on /voice/*
Dev-only escape hatch for non-loopback plaintext Hermes API bearer auth on /voice/*
values: 0, 1
RELAY_EXPERIMENTAL_REACH_ENABLED0Explicitly enable the experimental Hermes Reach connector
Explicitly enable the experimental Hermes Reach connector
values: 0, 1
RELAY_HERMES_CONFIG~/.hermes/config.yamlHermes config.yaml path
Hermes config.yaml path
RELAY_HOST0.0.0.0Bind address for the relay server
Bind address for the relay server
RELAY_LOG_LEVELINFOLogging level
Logging level
values: DEBUG, INFO, WARNING, ERROR
RELAY_MEDIA_ALLOWED_ROOTSExtra absolute-path roots allowed on register (os.pathsep-separated)
Extra absolute-path roots allowed on register (os.pathsep-separated)
RELAY_MEDIA_LRU_CAP500Max entries in the in-memory media registry before LRU eviction
Max entries in the in-memory media registry before LRU eviction
RELAY_MEDIA_MAX_SIZE_MB100Per-file size cap for POST /media/register
Per-file size cap for POST /media/register
RELAY_MEDIA_TTL_SECONDS86400How long a registered media entry stays fetchable
How long a registered media entry stays fetchable
RELAY_PORT8767Internal/direct compatibility listener port
Internal/direct compatibility listener port
RELAY_PROVIDER_USAGE_ENABLED0Opt in to the bearer-authenticated /usage/providers compatibility endpoint
Opt in to the bearer-authenticated /usage/providers compatibility endpoint
values: 0, 1
RELAY_SECURE_LINK_CERTgeneratedOptional TLS certificate path for Secure Link
Optional TLS certificate path for Secure Link
RELAY_SECURE_LINK_DASHBOARD_URLhttp://127.0.0.1:9119Loopback Dashboard upstream for the fixed /dashboard namespace
Loopback Dashboard upstream for the fixed /dashboard namespace
RELAY_SECURE_LINK_ENABLED0Enable optional Hermes Secure Link
Enable optional Hermes Secure Link
values: 0, 1
RELAY_SECURE_LINK_HOST0.0.0.0Secure Link bind and advertised host
Secure Link bind and advertised host
RELAY_SECURE_LINK_KEYgeneratedOptional TLS private-key path for Secure Link
Optional TLS private-key path for Secure Link
RELAY_SECURE_LINK_PORT9443Secure Link HTTPS port
Secure Link HTTPS port
RELAY_SSL_CERTTLS certificate path for production
TLS certificate path for production
RELAY_SSL_KEYTLS private key path for production
TLS private key path for production
RELAY_TRUST_PROXY_HEADERS0Trust X-Forwarded-Proto: https from your own reverse proxy
Trust X-Forwarded-Proto: https from your own reverse proxy
values: 0, 1
RELAY_WEBAPI_URLhttp://localhost:8642Hermes API Server URL
Hermes API Server URL

FAQ

Can I use this with hermes installed locally instead of remotely?

You don't need to. Native local Hermes already has the same file, image, and voice paths. Hermes-Relay is specifically for the remote-server case: when you want to use a Hermes that lives somewhere else (a home server, a GPU box, a cloud VM) from your laptop.