Self-Host Hermes Agent Securely with Localtonet

What this self-hosted architecture actually includes

This workflow has three separate components: the Hermes Agent runtime, the model inference provider, and the remote-access path. Keeping those components separate in your mental model is important because each one has a different trust boundary and failure mode.

Hermes runs on your machine and starts its gateway on the IPv4 loopback address 127.0.0.1, using port 8642 for the workflow covered here. A service bound to 127.0.0.1 accepts connections originating from the same host, but it is not directly listening on the machine's LAN interface or public interface. That is a useful default because it avoids unintentionally exposing the gateway to every device that can reach the host.

The Localtonet client must run on the same machine, or otherwise on a device that can reach the configured local target. For a target of 127.0.0.1:8642, the simplest and least ambiguous arrangement is to run our client on the same host as Hermes. The client establishes an outbound connection to a Localtonet relay server. Once the HTTP tunnel is created and started, requests sent to the assigned public HTTPS address are forwarded to the local gateway.

Localtonet provides the transport path, but it does not replace application authentication. Hermes should continue checking API_SERVER_KEY, and remote callers should provide that secret through the HTTP Authorization header using the Bearer authentication scheme.

Request flow from a remote client

A successful remote request follows this path:

1. The caller connects to the public HTTPS address assigned to the running Localtonet HTTP tunnel.
2. The caller includes the Hermes API key in the Authorization: Bearer header.
3. The request reaches the selected Localtonet relay.
4. The relay sends the request through the outbound client connection.
5. The Localtonet client forwards it to 127.0.0.1:8642.
6. Hermes evaluates the bearer credential and processes or rejects the request.

This design avoids exposing port 8642 directly through the router. It also lets you stop the public path independently by stopping the Localtonet tunnel. Stopping the tunnel does not necessarily stop Hermes, and stopping Hermes does not automatically delete the tunnel configuration.

Prerequisites and decisions to make before installation

Prepare the host before enabling any public access. The machine must be capable of running the Hermes version you intend to install, and it must be able to make outbound connections to any model provider and to the selected Localtonet relay. If Hermes will invoke local tools, the operating-system account running it must also have only the filesystem and command permissions that the agent genuinely needs.

Hermes installation commands, supported platforms, dependency versions, model requirements, and configuration schemas can change independently of Localtonet. The supplied evidence does not include a currently verified complete set of official Hermes installation instructions. For that reason, this draft does not present an installer command, package list, or model identifier as permanently valid. Before publication or execution, confirm those details against the current official Hermes documentation and release for your platform.

You should have the following items ready:

• A machine on which the current Hermes release is supported.
• A non-administrative operating-system account where practical.
• A model provider configuration supported by the installed Hermes release.
• An API credential for that provider if the selected provider requires one.
• A long, random value reserved for API_SERVER_KEY.
• A Localtonet account and a device-specific Localtonet authentication token.
• The Localtonet client installed on the machine that will reach 127.0.0.1:8642.
• A local HTTP client such as curl, or an equivalent tool capable of sending custom headers.

Choose the model boundary deliberately

If you use OpenRouter, do not choose a model only because its current price appears attractive. Model availability, pricing, request limits, context size, tool-calling support, provider routing, and privacy controls can change. Hermes versions can also enforce specific model capabilities. Confirm compatibility in the current Hermes and OpenRouter documentation rather than relying on a model ID copied from an older tutorial.

A remotely reachable agent can receive requests at any time while both Hermes and the tunnel are running. Hosted model usage can therefore be triggered remotely by anyone who possesses the bearer key. That can consume rate limits or create provider charges, depending on the current provider account and model. Treat the gateway credential as a high-impact secret even when you initially select a no-cost model.

Decide what the agent is allowed to do

Authentication answers who may submit a request. It does not limit what an authenticated agent can do after accepting that request. Review local tool permissions, shell access, writable directories, mounted volumes, inherited environment variables, and network access. Run Hermes with least privilege and avoid exposing sensitive home directories or infrastructure credentials unless the workflow strictly requires them.

Install and configure the Hermes Agent gateway

Install Hermes using the current official procedure for your operating system and the exact release you intend to run. Do not execute an installer copied from an old article without first verifying its domain, contents, supported platform, and current documentation. Installer scripts and dependency behavior can change, and this guide intentionally does not guess those details.

Complete the normal Hermes setup before configuring remote access. At minimum, that means the Hermes executable starts successfully, the selected model configuration is accepted, provider authentication works, and an ordinary local agent interaction can complete. A tunnel cannot repair an invalid model ID, a missing provider key, an unsupported model capability, or a broken Hermes installation.

Configure the model provider

Follow the current Hermes configuration schema to select OpenRouter or another supported provider. Use a model that meets the requirements enforced by your installed Hermes version. Because hosted catalogs and free model identifiers rotate, this article does not freeze a specific OpenRouter model name into the setup.

If Hermes reports that a model lacks tool support, has an insufficient context window, or is otherwise incompatible, choose a currently supported model rather than disabling a safety or compatibility check. If provider authentication fails, verify the provider key and account directly before proceeding.

Create the gateway authentication secret

Generate a long random secret with a trusted password manager or secret-management system. Do not use a dictionary word, a short password, the model provider key, or the Localtonet token. Store the resulting value as API_SERVER_KEY in the Hermes environment file used by this workflow:

API_SERVER_KEY=REPLACE_WITH_A_LONG_RANDOM_SECRET

The documented location for this workflow is ~/.hermes/.env. Restrict access to that file through the normal permissions available on your operating system. The placeholder above is not a usable secret and must not be copied into a real deployment unchanged.

Restart the gateway after changing its environment so the process loads the new value. Avoid passing the key directly on a shared command line because process listings and shell history can reveal command arguments.

Start the gateway on loopback

Start the Hermes gateway with:

hermes gateway

For this workflow, the expected listener is 127.0.0.1:8642. Read the startup output and confirm that the gateway reports the expected address and port. If your installed Hermes version uses a different command, configuration field, or default, stop and follow that version's official documentation. Do not change the Localtonet target to compensate for an unexplained startup discrepancy.

Confirm that the process remains available

Keep the terminal open during initial testing so you can observe startup and request errors. For long-running operation, use a service-management method appropriate to your operating system. The supplied evidence does not establish an official Hermes system service definition, restart policy, log path, or container deployment, so this guide does not invent one.

Whichever supervisor you choose, ensure that it runs Hermes under the intended account, loads the protected environment file, restarts only according to your operational policy, and does not print secrets into logs. Test startup after a host reboot before treating the deployment as unattended.

Verify the local gateway and bearer authentication

Do not create the public tunnel until the gateway works locally. Local verification separates Hermes configuration problems from tunnel problems and gives you a baseline for comparing responses.

Use a real protected route

The exact API route can vary with the Hermes gateway version and enabled interface. The supplied evidence establishes the gateway address and bearer authentication requirement, but it does not establish a version-stable request path and body for a complete inference request. Use a protected route documented by your installed Hermes release and substitute it for REPLACE_WITH_DOCUMENTED_GATEWAY_PATH below.

First, make a request without credentials:

curl -i \
  http://127.0.0.1:8642/REPLACE_WITH_DOCUMENTED_GATEWAY_PATH

The protected endpoint should reject the request rather than execute it. This guide does not assert a specific status code because that behavior must be confirmed for the installed Hermes version. A connection-refused error is not an authentication rejection. It means no process accepted the connection at the target address and port.

Next, send the same request with the configured bearer key:

curl -i \
  -H "Authorization: Bearer YOUR_HERMES_API_SERVER_KEY" \
  http://127.0.0.1:8642/REPLACE_WITH_DOCUMENTED_GATEWAY_PATH

Replace the placeholder locally. Do not paste the completed command into tickets, chat rooms, screenshots, or shared shell transcripts. If the documented route requires a method, content type, or JSON body, add exactly what the current Hermes documentation specifies.

Interpret the results carefully

The minimum acceptable local result is that an unauthenticated request to a protected route is denied and the equivalent correctly authenticated request reaches the expected gateway behavior. Do not infer authentication from a successful TCP connection alone.

Expose Hermes with a Localtonet HTTP tunnel

Once local authentication works, create the remote path. Our HTTP tunnel should point to the existing loopback listener. You do not need to rebind Hermes to a LAN address or configure an inbound router port.

Install and run the Localtonet client on the Hermes host. Authenticate the client with its device-specific token, then use the dashboard to create and start the HTTP tunnel. Available relay servers and regions must be selected from the current product or dashboard rather than copied from an article.

HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, subject to what is available in the current product and account. These options serve the target at a public HTTPS address. If you plan to use a custom domain, verify the current DNS requirements before changing records because exact DNS instructions are not established by the supplied context.

For the current dashboard workflow, consult our Localtonet HTTP tunnel documentation alongside these security checks. Documentation should supplement the local Hermes validation, not replace it.

Test authorized and unauthorized remote requests

Remote verification should repeat the same two-request pattern used locally. Change only the base address from http://127.0.0.1:8642 to the public HTTPS address assigned by Localtonet. Use the same real protected Hermes path, HTTP method, content type, and body in both tests.

Test without the bearer key

curl -i \
  https://YOUR_ASSIGNED_LOCALTONET_HOST/REPLACE_WITH_DOCUMENTED_GATEWAY_PATH

The request should reach the public endpoint but must not execute the protected Hermes operation. Confirm the actual rejection behavior against the current Hermes version. If an unauthenticated request succeeds, stop the tunnel immediately and correct the Hermes authentication configuration before continuing.

Test with the bearer key

curl -i \
  -H "Authorization: Bearer YOUR_HERMES_API_SERVER_KEY" \
  https://YOUR_ASSIGNED_LOCALTONET_HOST/REPLACE_WITH_DOCUMENTED_GATEWAY_PATH

A correctly formed request should now reach the same application behavior observed during local testing. If local access works but remote access does not, focus on the Localtonet client state, tunnel state, selected device, local target, and public URL. If both local and remote requests reach Hermes but inference fails, focus on Hermes and the configured model provider.

Do not confuse transport success with application success

Receiving any HTTP response proves only that an HTTP component answered. A missing route, an authentication rejection, and a provider failure are all responses, but they represent different layers. Compare response headers, status, body, Hermes logs, and tunnel state without exposing secrets.

Complete remote verification from a genuinely separate network where practical. Testing the public URL from the same host is useful, but a second device using another connection better represents the real client path. Do not store the bearer secret in browser bookmarks or query strings. Use a client that can set the Authorization header.

Security practices for an internet-reachable AI agent

A gateway that can instruct an agent is more sensitive than a read-only status page. A valid caller may be able to trigger model usage, local file operations, network requests, or tools enabled in Hermes. The exact impact depends on the installed version and your configuration, so secure both access to the gateway and the agent's local capabilities.

Keep secrets out of URLs and request bodies

Send the gateway key in the Authorization header. Do not append it to the public URL as a query parameter. URLs can appear in browser history, proxy logs, monitoring systems, analytics, screenshots, and referrer information.

Be careful when using command-line tools. A literal header value can remain in shell history. Prefer a secure client-side secret mechanism where available. If you temporarily place a secret in an environment variable, understand how that environment is inherited and avoid printing it during debugging.

Plan for key rotation

A practical rotation sequence is to stop the public tunnel, update API_SERVER_KEY through the supported Hermes configuration, restart Hermes, repeat the local unauthorized and authorized tests, update approved remote clients, and then restart the tunnel. This sequence minimizes the period in which the gateway is publicly reachable with an uncertain authentication state.

Protect the host, not only the endpoint

Patch the operating system and review packages installed by the Hermes setup process. Protect the user's home directory, provider credentials, SSH keys, cloud credentials, browser profiles, and other secrets that an agent process might reach. If the machine contains unrelated sensitive data, consider stronger workload separation rather than relying only on application authentication.

Routine operation and troubleshooting

Recommended startup order

1. Start Hermes and confirm it listens on 127.0.0.1:8642.
2. Run the local unauthenticated test against a protected route.
3. Run the local authenticated test and confirm expected behavior.
4. Start the Localtonet client and confirm the correct device is connected.
5. Start the HTTP tunnel.
6. Run both remote tests through the assigned public HTTPS address.

This order prevents the public path from becoming active before you know authentication is working. It also isolates errors efficiently.

Recommended shutdown order

1. Stop the Localtonet tunnel to remove the public path.
2. Allow any intended in-flight agent task to finish according to your operational policy.
3. Stop Hermes if local gateway access is no longer needed.
4. Delete the tunnel configuration only when you do not intend to reuse it.

The public URL does not respond

Confirm that the Localtonet client is connected, the correct device token is in use, and the tunnel has been started. Then verify that you are using the currently assigned address shown in the dashboard. A configured but stopped tunnel is not available.

Next, repeat the local request. If 127.0.0.1:8642 also fails, troubleshoot Hermes first. If local access works, confirm that the tunnel target is exactly 127.0.0.18642 on the device running the client.

Remote requests return an authentication error

Confirm that the header name is Authorization, the scheme is Bearer, and a space separates the scheme from the secret. Check that the running Hermes process loaded the same API_SERVER_KEY value used by the client. Restart Hermes after changing the environment.

Avoid solving this problem by disabling authentication. Compare a known working local authenticated request with the remote request, changing only the base URL.

Unauthenticated remote requests succeed

Stop the tunnel immediately. Verify that you tested a route protected by Hermes rather than an unprotected informational or health route. Confirm that API_SERVER_KEY is present in the environment loaded by the gateway and that the process was restarted after configuration. Do not resume public access until the local negative test reliably fails and the local positive test succeeds.

The gateway authenticates but the model fails

This usually points beyond the tunnel. Check the model provider credential, selected model identifier, compatibility requirements, account state, current rate limits, and provider availability. Hosted model catalogs can change. A model that worked previously may be removed, renamed, rerouted, or subjected to different limits.

Also check whether a single user operation causes multiple model calls. Agent workflows can consume provider requests for planning, tool execution, follow-up processing, or retries. Do not assume that one user message always equals one provider request.

The service works locally but the tunnel cannot reach it

Make sure the Localtonet 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 our client runs on a different computer, 127.0.0.1:8642 refers to that other computer, not the Hermes host.

A cross-device target requires Hermes to be reachable from the client device through an appropriate network address, which changes the security design. The safest workflow described here avoids that ambiguity by colocating the client and Hermes.

The service disappears after a reboot

Determine whether Hermes, the Localtonet client, or both failed to restart. They are independent processes. Also remember that the tunnel must be running, not merely saved in the dashboard. Review the service-management mechanism you selected for each process, but do not expose environment files or tokens while collecting logs.

Frequently asked questions