Remote Hermes work profile against local MTPLX

remote-work-profile-guide.md

Running a Remote Hermes "work" Profile Against a Local MTPLX Model

Goal: Install and configure a Hermes gateway on a remote host (192.168.1.68) with a profile named work, pointed at an MTPLX local model server that runs on your current machine. Then connect to that remote work agent from here.

What is validated here: The MTPLX endpoint http://127.0.0.1:8000/v1 with API key sk-mtplx-1234 was tested with a real chat completion and returned a valid response. The config block below mirrors an existing working profile. The install itself was not run — this guide is for you to run on the remote host.

Critical detail: MTPLX runs on this machine. The remote host's work profile must point its model URL at this machine's LAN address (for example http://192.168.1.10:8000/v1), not 127.0.0.1. On the remote host, 127.0.0.1 is the remote host itself, which has no MTPLX.

---

Part 0 — Confirm the local MTPLX is reachable from the remote host

Do this on the remote host (after SSHing in). It must reach the MTPLX on this machine over the LAN.

1. Find this machine's LAN IP here:

   # macOS
   ipconfig getifaddr en0 || ipconfig getifaddr en1
   # Linux
   hostname -I

2. From the remote host, test that MTPLX answers with the key:

   curl -s http://<THIS-LAN-IP>:8000/health -H "Authorization: Bearer sk-mtplx-1234" | head -c 200

   If it times out, the local MTPLX is bound to loopback only. Start it bound to the LAN (see the MTPLX docs / mtplx --help) or ensure the firewall allows port 8000 from the remote host. This is the most common failure point.

---

Part 1 — Install Hermes on the remote host

SSH in, then run the official installer:

ssh cody.bunch@192.168.1.68
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The installer sets up uv, Python, the virtualenv, and the launcher. On completion, hermes is on PATH.

---

Part 2 — Create the work profile

The profile becomes its own command (work chat, work gateway start, etc.).

work setup          # configure API keys, model, gateway tokens

Because MTPLX is local-only, work setup will not know about it. Configure the model manually in Part 3 instead.

---

Part 3 — Point work at the local MTPLX

Edit the remote profile's config to add a custom_providers block. Use hermes config set (never hand-edit config.yaml — a stray indent breaks the live gateway).

1. Set the model on the profile:

   work config set model.default wang-yang-ornith-1.5-35b-a3b-mtplx-4bit

2. Append the custom provider. Substitute <THIS-LAN-IP> with the address you found in Part 0:

   work config set custom_providers '[{"name":"mtplx-ornith","base_url":"http://<THIS-LAN-IP>:8000/v1","key_env":"HERMES_CUSTOM_<THIS-LAN-IP>_8000_API_KEY","model":"wang-yang-ornith-1.5-35b-a3b-mtplx-4bit","models":{"wang-yang-ornith-1.5-35b-a3b-mtplx-4bit":{}},"models_discovered":true}]'

3. Set the API key in the remote profile's .env (secrets live in .env, settings live in config.yaml):

   echo 'HERMES_CUSTOM_<THIS-LAN-IP>_8000_API_KEY=sk-mtplx-1234' >> ~/.hermes/profiles/work/.env

4. Verify the model resolves:

   work doctor

---

Part 4 — Run the gateway / dashboard on the remote host

To connect from this machine you need the remote host to run a dashboard backend (it exposes the /api/ws socket that Hermes Desktop attaches to).

1. Bind to the LAN address so the auth gate is active and the remote client can reach it:

   work gateway run --bind 0.0.0.0:9119

   (Run it in the background or under a process manager so it stays up. On Linux, work gateway install + work gateway start makes it a service.)

2. Grab the dashboard session token from the remote host's logs or config; the Desktop login (Part 5) needs it for Session token auth.

---

Part 5 — Connect to the remote work agent from here

Open Hermes Desktop on this machine. Go to Settings → Gateway → Remote Gateway and add a connection:

• Name: work (a unique device name, max 64 chars).
• Gateway URL: http://<REMOTE-HOST>:9119 (the remote host's address, not loopback).
• Authentication:
  • Session token — paste the token from the remote host's dashboard.
  • OAuth — sign in through the Nous Portal flow (no token to paste).
• Click Save connection, then Test and wait for "Reachable".

Once it reports Reachable, switch the profile switcher to work and chat with the remote agent. Each profile you connect is discovered from the gateway you attach to — one connection covers all profiles on that host.

---

Troubleshooting

• "Connection test failed" — the remote backend is not reachable. Confirm work gateway run is running on the remote host, port 9119 is open, and (for token auth) the token is current. Re-run Test.
• Model errors / "missing or invalid API key" — the remote work profile's base_url points at 127.0.0.1 (wrong host) or the .env key name does not match the key_env in custom_providers. Re-check Part 3.
• Model times out — the local MTPLX on this machine is not reachable from the LAN (bound to loopback, or firewall blocks 8000). Fix MTPLX binding; see Part 0.
• "Backend down" — the remote dashboard is not running. Start it (Part 4).
• WebSocket passes but HTTP fails — a proxy, firewall, or gateway auth/origin guard is blocking /api/ws.

---

Summary of the data flow

this machine (here)              remote host 192.168.1.68
--------------------------------   ------------------------------
MTPLX local model server          work profile
  127.0.0.1:8000  <---- base_url ---->  http://<THIS-LAN-IP>:8000/v1
  key: sk-mtplx-1234                  key: in ~/.hermes/profiles/work/.env
Hermes Desktop                       work gateway run (dashboard :9119)
  Settings -> Gateway                  -> Session token or OAuth
  Remote Gateway login                 -> profile switcher -> work