Self-Host Hermes Agent Securely with Localtonet

What this self-hosted architecture includes

This deployment has three independent components: the Hermes Agent runtime, the model inference provider, and the remote-access path. Keeping them separate is important because they have different trust boundaries, credentials, lifecycle controls, and failure modes.

Hermes runs the agent process and gateway on your machine. For the Hermes Agent v0.21.0 workflow covered here, the gateway command listens on the IPv4 loopback address 127.0.0.1 and port 8642. A loopback listener accepts connections from the same host without opening the service on the machine's LAN or public interface.

The Localtonet client runs on that same machine and connects outward to a selected Localtonet relay. When the HTTP tunnel is running, requests to its public HTTPS address travel through that outbound connection and are forwarded to 127.0.0.1:8642. The public path exists only while the selected client is connected and the tunnel is running.

Localtonet supplies transport and public reachability. Hermes still supplies application-level authorization through API_SERVER_KEY. A remote client must send the configured value in an Authorization: Bearer header. Do not disable this protection merely because the gateway is reached through a tunnel.

Request flow from a remote client

1. The caller sends an HTTPS request to the address of the running Localtonet HTTP tunnel.
2. The request includes the Hermes key in the Authorization: Bearer header.
3. The request reaches the selected Localtonet relay.
4. The relay carries it through the outbound connection maintained by the Localtonet client.
5. The client forwards the HTTP request to 127.0.0.1:8642.
6. Hermes validates the Bearer credential and either rejects or processes the API request.
7. If the request requires inference, Hermes contacts the configured model provider.

Stopping the Localtonet tunnel removes the public path without necessarily stopping Hermes. Stopping Hermes leaves no application listening behind the tunnel but does not delete the saved tunnel configuration. Treat these as separate lifecycle controls.

Prerequisites and supported installation paths

The installation commands below are version-qualified for Hermes Agent v0.21.0. Before using them with a later release, compare the instructions with the current official Hermes Agent repository and the installer content served from the official Nous Research domain. Do not run a downloaded installation script if its domain, contents, or behavior differs from the current project documentation.

In the v0.21.0 installation workflow, the installer obtains the Hermes runtime dependencies it manages, including Python 3.11 through uv, Node.js, ripgrep, and FFmpeg. The project code is placed under ~/.hermes/hermes-agent/, user data and configuration are stored under ~/.hermes/, and the launcher is installed at ~/.local/bin/hermes on the shell-based path.

You also need:

• An OpenRouter account and API key, or another provider supported by the Hermes release you install.
• A currently available model compatible with the Hermes agent workflow.
• A long, independently generated value for API_SERVER_KEY.
• A Localtonet account and a device-specific Localtonet authentication token.
• The Localtonet client installed on the same host as Hermes for the loopback design used here.
• curl or another HTTP client capable of sending headers, JSON request bodies, and POST requests.

Plan the agent's local permissions

A valid API caller can ask the agent to use whichever tools are enabled. Authentication controls who can submit a request, but it does not reduce the operating-system permissions available after the request is accepted. Run Hermes with a non-administrative account where practical and limit access to files, commands, mounted storage, inherited environment variables, and network destinations.

Choose the model from current provider data

OpenRouter model IDs, provider routes, capabilities, context sizes, pricing, and availability can change independently of Hermes. Do not treat an old model ID or a past free-price label as permanent. Consult the current OpenRouter catalog and confirm that the selected model satisfies the requirements reported by your installed Hermes release.

The OpenRouter API key can create usage under your provider account. A remotely reachable agent may make several model calls for a single user task because planning, tool execution, retries, and follow-up processing can each require inference. Set provider-side limits where available and monitor actual usage.

Install Hermes Agent

Linux, macOS, WSL2, and Android Termux

Confirm that the prerequisite packages are present. Package-manager commands vary by operating system, so use the appropriate package manager for your host. Then inspect and run the official installer from Nous Research:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh
bash /tmp/hermes-install.sh
rm /tmp/hermes-install.sh

Reviewing the downloaded file before execution makes the installer source and actions visible. If the current Hermes project publishes a checksum or release-specific installation procedure, prefer that current procedure.

Native Windows PowerShell

In PowerShell, download the official installer, inspect it, and then execute it:

$installer = Join-Path $env:TEMP "hermes-install.ps1"
Invoke-WebRequest "https://hermes-agent.nousresearch.com/install.ps1" -OutFile $installer
Get-Content $installer
& $installer
Remove-Item $installer

Use the native Windows path or the WSL2 path consistently. A Hermes installation inside WSL2 is separate from a native Windows installation, and 127.0.0.1 must be interpreted from the environment where the Localtonet client runs.

Reload the shell and verify the executable

The shell installer places the launcher in ~/.local/bin. Open a new terminal after installation. If the current terminal has not reloaded its startup file, reload the appropriate file:

source ~/.bashrc

For Zsh:

source ~/.zshrc

Then verify that the command is available:

command -v hermes
hermes --version

The first command should resolve to the installed launcher, commonly ~/.local/bin/hermes on the shell-based installation. The version command should identify the release you intend to use. This tutorial's gateway route, listener, and authentication expectations are pinned to v0.21.0. Recheck the official Hermes release documentation if your installed version differs.

Configure OpenRouter and protect the gateway

Create an OpenRouter API key

Create a key in your OpenRouter account and review the current setup instructions in the OpenRouter documentation. Do not paste the real key into an article, configuration example, or command that will be shared.

On a Unix-like shell, read the credential without echoing it and pass it to the Hermes configuration command:

read -rsp "OpenRouter API key: " OPENROUTER_API_KEY
printf '\n'
hermes config set OPENROUTER_API_KEY "$OPENROUTER_API_KEY"
unset OPENROUTER_API_KEY

For Hermes Agent v0.21.0, this stores the provider credential through the Hermes configuration workflow under ~/.hermes/. Restrict access to that directory:

chmod 700 ~/.hermes
chmod 600 ~/.hermes/.env 2>/dev/null || true

In PowerShell, use a secure secret-entry and storage procedure suitable for your environment. Avoid placing the literal credential in PowerShell history, scripts, or transcripts.

Select an OpenRouter model

Hermes stores its model selection in ~/.hermes/config.yaml. The following configuration shape selects OpenRouter:

model:
  provider: openrouter
  default: z-ai/glm-5.2:free

The example model above was listed in the OpenRouter catalog for the tested September 2026 v0.21.0 workflow. It is not a permanent availability or pricing promise. Before using it, confirm that the exact ID still appears in the current OpenRouter catalog and that Hermes accepts it. If it is no longer available, replace only the default value with a currently supported model ID.

A usable result is not merely that the YAML parses. Hermes must start without rejecting the model, OpenRouter must accept the provider key, and an actual agent request must complete. If startup reports a missing capability or insufficient context, choose a compatible current model rather than bypassing the check.

Create a separate Hermes API key

Hermes Agent v0.21.0 reads the gateway key from API_SERVER_KEY in ~/.hermes/.env. The following Python command prompts without echoing the secret, updates the setting without printing it, and restricts the file to its owner:

python3 - <<'PY'
from getpass import getpass
from pathlib import Path
import os

env_path = Path.home() / ".hermes" / ".env"
env_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)

secret = getpass("New Hermes API server key: ").strip()
if len(secret) < 32:
    raise SystemExit("Use a random API server key of at least 32 characters.")

lines = []
if env_path.exists():
    lines = [
        line for line in env_path.read_text().splitlines()
        if not line.startswith("API_SERVER_KEY=")
    ]

lines.append(f"API_SERVER_KEY={secret}")
env_path.write_text("\n".join(lines) + "\n")
os.chmod(env_path, 0o600)
print(f"Updated {env_path} with owner-only permissions.")
PY

Generate the value with a password manager or trusted secret generator. Do not reuse the OpenRouter key, Localtonet token, login password, or a key shown in an example.

Start the v0.21.0 gateway

hermes gateway

Keep this terminal open during initial verification. The expected startup result for v0.21.0 is a gateway listening on 127.0.0.1:8642. Treat a different port, wildcard listener, authentication warning, provider error, or immediate process exit as a failed startup. Resolve that discrepancy before creating a tunnel.

Verify the gateway and authentication locally

Test Hermes locally before involving Localtonet. The v0.21.0 gateway exposes an OpenAI-compatible chat-completions route at /v1/chat/completions. It expects a POST request with JSON and, when API_SERVER_KEY is configured, a Bearer credential.

Create a request body using the same model ID configured in ~/.hermes/config.yaml:

cat > /tmp/hermes-request.json <<'JSON'
{
  "model": "z-ai/glm-5.2:free",
  "messages": [
    {
      "role": "user",
      "content": "Reply with exactly HERMES_OK and do not use tools."
    }
  ]
}
JSON

If you selected another current model, replace the JSON model value with that exact identifier.

Negative test: omit the credential

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/hermes-request.json \
  http://127.0.0.1:8642/v1/chat/completions

The expected v0.21.0 result is an HTTP authentication rejection, with no model operation executed. An HTTP 401 Unauthorized response satisfies this negative test. A successful completion fails the security check. Stop and confirm that API_SERVER_KEY exists in ~/.hermes/.env, then restart the gateway.

A connection-refused message is not a successful negative test. It means no process accepted a connection on 127.0.0.1:8642. A 404 response indicates a route or version mismatch rather than proof that authentication works.

Positive test: read the secret without printing it

read -rsp "Hermes API server key: " HERMES_API_KEY
printf '\n'

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  --data-binary @/tmp/hermes-request.json \
  http://127.0.0.1:8642/v1/chat/completions

unset HERMES_API_KEY

The expected positive result is HTTP 200 with a JSON chat-completion response. For the supplied prompt, the assistant content should be HERMES_OK, although model formatting can vary. A successful HTTP status and a valid completion object establish that the route, Bearer key, provider configuration, model selection, and inference path are working together.

Remove the temporary request file when testing is complete:

rm -f /tmp/hermes-request.json

Create and start the Localtonet HTTP tunnel

Install our client on the Hermes host so that 127.0.0.1 refers to the same machine on which the gateway is listening. Use the current operating-system instructions in the Localtonet client and tunnel documentation. Authenticate the client with the device-specific token from your dashboard, but never include that token in screenshots or shared commands.

The current HTTP workflow uses the HTTP tunnel page, an HTTP Process Type, the connected device's AuthToken, an available server, and the local IP address and port. Follow this sequence:

The resulting target must be exactly 127.0.0.1:8642. If the dashboard shows another device, address, port, or disconnected token, stop and correct the configuration before testing.

The Localtonet HTTP tunnel documentation contains the current dashboard workflow. If you use Custom Domain, check the current DNS instructions there before changing records. DNS requirements can change and should not be inferred from the Random Sub Domain workflow.

Verify unauthorized and authorized remote access

Repeat the local tests against the assigned Localtonet HTTPS address. Keep the route, method, headers, and JSON body identical. Only the base address should change.

Recreate the request body if you removed it:

cat > /tmp/hermes-request.json <<'JSON'
{
  "model": "z-ai/glm-5.2:free",
  "messages": [
    {
      "role": "user",
      "content": "Reply with exactly HERMES_OK and do not use tools."
    }
  ]
}
JSON

Set the public base URL without adding the API key to it:

read -rp "Localtonet public HTTPS base URL: " HERMES_PUBLIC_URL
HERMES_PUBLIC_URL="${HERMES_PUBLIC_URL%/}"

Remote negative authentication test

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/hermes-request.json \
  "$HERMES_PUBLIC_URL/v1/chat/completions"

The expected result for the v0.21.0 API is an HTTP 401 Unauthorized response. If the operation succeeds without a Bearer key, stop the Localtonet tunnel immediately and correct the Hermes authentication configuration.

Remote positive authentication test

read -rsp "Hermes API server key: " HERMES_API_KEY
printf '\n'

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  --data-binary @/tmp/hermes-request.json \
  "$HERMES_PUBLIC_URL/v1/chat/completions"

unset HERMES_API_KEY HERMES_PUBLIC_URL
rm -f /tmp/hermes-request.json

The expected result is HTTP 200 with the same type of chat-completion JSON observed locally. Test from a separate device or network where practical. A second network confirms the full remote path rather than only the host's ability to resolve and call its own public endpoint.

An HTTP response alone does not prove success. A 401, 404, provider error, and successful completion all show that an HTTP component answered, but they indicate different layers. Compare the status, body, Hermes terminal output, connected client, tunnel state, and configured target.

Harden an internet-reachable AI agent

An AI-agent gateway is more sensitive than a read-only web page. An authenticated request may trigger model usage, shell commands, local file operations, network requests, or other enabled tools. The impact depends on your Hermes configuration, so protect both the gateway and the operating-system account behind it.

Keep keys out of URLs and saved commands

Send API_SERVER_KEY only in the Authorization header. Query-string secrets can appear in browser history, logs, analytics, monitoring systems, screenshots, and referrer information.

A command containing a literal Bearer value may remain in shell history. The examples above use a non-echoed prompt and a temporary shell variable so the value is not embedded in the saved command. Clear variables after each test and avoid enabling shell tracing while handling secrets.

Use a controlled key-rotation sequence

1. Stop the Localtonet tunnel.
2. Generate a new random Hermes gateway key.
3. Update API_SERVER_KEY in ~/.hermes/.env.
4. Restart hermes gateway.
5. Repeat the local negative and positive tests.
6. Update approved clients through a secure channel.
7. Start the tunnel and repeat both remote tests.

If a Localtonet device token is exposed, replace it through the appropriate account and device workflow rather than treating a Hermes key rotation as sufficient. If the OpenRouter key is exposed, revoke or rotate it through OpenRouter and review provider usage.

Protect the host itself

Patch the operating system and review the software installed for Hermes. Protect home directories, SSH keys, cloud credentials, browser profiles, source repositories, and provider secrets. Where an agent does not need access, remove permission instead of relying on a prompt telling the agent not to use it.

Routine operation and troubleshooting

Recommended startup order

1. Start hermes gateway.
2. Confirm the v0.21.0 listener is 127.0.0.1:8642.
3. Run the local request without a key and confirm 401 Unauthorized.
4. Run the local request with the correct key and confirm a successful completion.
5. Start the Localtonet client and confirm that the intended device is connected.
6. Start the HTTP tunnel.
7. Repeat the negative and positive tests through the public HTTPS address.

This sequence ensures that the public path is not enabled until application authentication is known to work.

Recommended shutdown order

1. Stop the Localtonet tunnel to remove the public route.
2. Allow intended in-flight work to complete according to your operating policy.
3. Stop Hermes if the local gateway is no longer required.
4. Delete the tunnel only if you do not intend to reuse its saved configuration.

The public URL does not respond

Confirm that the selected Localtonet client is connected and the tunnel has been started. Creating or saving a tunnel does not make it active. Verify that you are using the public address currently displayed for that running tunnel.

Repeat the local request against http://127.0.0.1:8642/v1/chat/completions. If the local request also fails, troubleshoot Hermes first. If local access succeeds, confirm that the Localtonet target is exactly 127.0.0.1:8642, with the colon between the IP address and port.

The tunnel returns an authentication error

Confirm that the header name is Authorization, the scheme is Bearer, and one space separates the scheme from the key. Check that the running Hermes process was restarted after the value in ~/.hermes/.env changed.

Compare a working local request with the remote request and change only the base URL. Do not disable authentication to solve a header or secret mismatch.

Unauthenticated remote requests succeed

Stop the tunnel immediately. Confirm that you tested POST /v1/chat/completions rather than an informational endpoint. Verify that API_SERVER_KEY exists in the environment file loaded by Hermes and restart the gateway. Do not resume public access until the local negative request returns 401 and the authenticated request succeeds.

The API authenticates but inference fails

This normally points beyond the tunnel. Check the OpenRouter credential, current model identifier, model availability, account state, current limits, and any compatibility message emitted by Hermes. Do not assume a past free model remains available or free.

One user task may result in several provider requests. Agent planning, tool calls, retries, and follow-up interpretation can consume additional provider capacity. Review actual provider usage rather than estimating it from the number of user messages.

Local access works, but the tunnel cannot reach Hermes

Make sure our client runs on the Hermes host. The address 127.0.0.1 always refers to the loopback interface of the device making the connection. If the Localtonet client runs on another computer, 127.0.0.1:8642 points to that other computer, not the Hermes machine.

Exposing Hermes to a separate client device would require a network-reachable listener and a revised security design. This tutorial deliberately avoids that arrangement by colocating Hermes and the Localtonet client.

The hermes command is missing after installation

Open a new terminal or reload ~/.bashrc or ~/.zshrc. Check whether ~/.local/bin is in PATH and whether ~/.local/bin/hermes exists. If it does not, inspect the installer output before rerunning anything.

The service disappears after reboot

Hermes and the Localtonet client are independent processes. Determine which one did not restart, then confirm that the tunnel itself is running rather than merely saved. If you configure operating-system service management, ensure the process runs as the intended user, loads the protected environment file, and does not print secrets into logs.

This tutorial does not prescribe a Hermes system service because service definitions and restart behavior differ across supported platforms. Whichever supervisor you choose, test a full host reboot, then repeat the local and remote negative and positive checks.

Frequently asked questions