OAuth over SSH / Remote Hosts
OAuth over SSH / Remote Hosts
Start with meaning, then move to detail.
This lesson explains OAuth over SSH / Remote Hosts as part of extending Hermes and connecting external tools. You will learn what it does, when it matters, and the smallest safe test that proves it works.
If you are new, do not memorize names. Focus on three questions: what problem does this solve, what access does it need, and how can you verify the result?
For practice, inspect the first example, identify its effects, run it on test data, and compare the result with the source claim.
For advanced readers, inspect TL;DR, Which Providers Need This, MCP Servers, then verify failure modes and version compatibility.
Complete installation and one successful task before adding new capabilities.
A clear outcome before you read.
- Understand OAuth over SSH / Remote Hosts without assumed prior knowledge.
- Separate the source description from what still needs testing in your environment.
- Read the first command and identify its inputs and outputs before copying it.
Short definitions before the details.
- MCP
- A standard way to expose external tools, resources, and services to an agent.
- Provider
- The service that runs or provides access and authentication to a model.
- Session & memory
- A session holds conversation context, while memory keeps selected facts that should persist.
- Browser / CDP
- A layer for programmatic browser control and page or event inspection.
How to complete browser-based OAuth (Spotify, MCP servers) when Hermes runs on a remote machine, container, or behind a jump box
What does the source say, and in what order?
- 01TL;DR
Start here to understand the core idea or structure.
- 02Which Providers Need This
Read this after the foundation, then connect it to the previous step.
- 03MCP Servers
Read this after the foundation, then connect it to the previous step.
- 04Why the listener can't just bind 0.0.0.0
Read this after the foundation, then connect it to the previous step.
- 05Step-by-step: single SSH hop
Read this after the foundation, then connect it to the previous step.
- 061. Start the tunnel from your local machine
Read this after the foundation, then connect it to the previous step.
- 072. In a separate SSH session, run the auth command
Read this after the foundation, then connect it to the previous step.
- 083. Open the URL in your local browser
Read this after the foundation, then connect it to the previous step.
- 09Step-by-step: through a jump box
Read this after the foundation, then connect it to the previous step.
- 10Mosh, tmux, ssh ControlMaster
Finish here to verify the result and special cases.
Copy only after you understand the effect.
# On your local machine (laptop), in a separate terminal:
ssh -N -L 43827:127.0.0.1:43827 user@remote-host
# In your existing SSH session on the remote machine:
hermes auth spotify --no-browser
# → Hermes prints an authorize URL. Open it in a browser on your laptop.
# → Your browser redirects to 127.0.0.1:43827/callback, the tunnel forwards
# the request to the remote listener, login completes.MCP OAuth: authorization required.
Open this URL in your browser:
https://mcp.linear.app/authorize?response_type=code&...
Or paste the redirect URL here (or the ?code=...&state=... portion) and press Enter:
> https://mcp.linear.app/callback?code=abc123&state=xyz
Got authorization code from paste — completing flow.ssh -N -L <port>:127.0.0.1:<port> user@remote-hostRead the first command and identify its inputs and outputs before copying it.
Match every command to your installed Hermes version, review the files and accounts it can reach, and use non-sensitive data for the first test. If this explanation differs from the source, the official source wins.