Skip to main content
Hermes Agent is the self-improving agent runtime from Nous Research. It installs skills following the agentskills.io open standard, which means it can use the same authsome skill that Claude Code, Cursor, and other agentskills.io-compatible runtimes use. Authsome ships an agentskills.io-compatible SKILL.md at skills/authsome/. Once installed into Hermes, the agent runs authsome login, authsome list, and authsome run itself whenever it needs a credential. You never paste a token into a Hermes prompt.
The agent drives login. When Hermes hits a missing credential it runs authsome login <provider> itself, opens a browser on your machine for OAuth consent, and picks up from there. Pre-running logins is only useful if you want to seed a credential ahead of time.

​
Install the skill

Authsome’s skill installs into Hermes with a single command:
Hermes fetches the skill from agentrhq/authsome on GitHub, registers it locally, and the agent can call it on the next turn. Tell Hermes to use the skill:
Hermes reads the skill manifest and runs the matching authsome commands. The skill teaches Hermes the list → login → run flow plus authsome’s safety rules (no client_secret in shell history, no --scopes workaround for missing access).

​
What the integration gives you

  • One login per service. OAuth2 and API-key flows run from inside Hermes. The skill drives the same authsome login commands a human would type.
  • No credentials in prompts or files. Hermes never sees raw tokens. The skill calls authsome, which collects secrets through a local browser bridge or the masked terminal fallback.
  • Automatic refresh. Tokens stay fresh for every agent run Hermes triggers. You do not re-authenticate when an access token expires.
  • The same vault. Connections you create through Hermes are stored in ~/.authsome/, identical to connections created from the regular CLI or any other agentskills.io-compatible runtime. Nothing is duplicated.

​
First run

A typical first session looks like this:
1

Ask Hermes what's already configured

Hermes runs authsome list and reports which providers are bundled, configured, and connected.
2

Log in to a provider

Hermes opens a browser to the OAuth2 PKCE flow. You approve the requested scopes, the callback lands on http://127.0.0.1:7998/auth/callback/oauth, and authsome stores the encrypted record.
3

Use the connection

Hermes runs the agent under authsome run. The HTTP proxy injects the Authorization header at the api.github.com host. The agent’s environment never contains the raw token.

​
Common prompts

​
Why this is the safe pattern

Without authsome, agents running inside Hermes typically read tokens from environment variables, .env files, or shell history. Each of those surfaces leaks easily: authsome run is the recommended pattern for any Hermes agent that calls third-party APIs. The child process never sees the real secret because the proxy injects headers at request time.

​
Multi-account workflows

Most real workflows need at least two accounts (personal and work GitHub, or a personal and team OpenAI key). The skill plays well with named connections:
Hermes runs:
Read it back:
Hermes runs the agent under authsome run --connection work -- ....

​
Without the skill

If you want to drive authsome from Hermes without installing the skill (for example, a one-off script Hermes spawns), the same proxy pattern works directly:
Hermes can also drop below the CLI into the Python library when it needs explicit per-call control:
See Run agents with the proxy and Python library for the full surface.

​
What the skill cannot do

  • It cannot type a client_secret for you. Authsome refuses sensitive values as command-line arguments. The browser bridge is the only path.
  • It cannot bypass the proxy CA requirement. HTTPS interception needs the mitmproxy CA trusted on the machine. The first authsome run writes the CA to ~/.mitmproxy/. See Proxy networking.
  • It cannot share the vault across machines. Hermes on a second machine has its own ~/.authsome/. Re-run logins there.

​
Troubleshooting

If a Hermes-driven login hangs:
  • Run authsome doctor directly from the terminal to surface initialization errors.
  • Run authsome --verbose login <provider> to see the full flow including the daemon round-trips.
  • Run authsome log to inspect recent audit events from the daemon.
For provider-specific errors, see OAuth callbacks and Token refresh.

​
What’s next

Run agents with the proxy

The proxy injection model the skill uses under the hood.

Python library

Use authsome export or the daemon HTTP API when the proxy is not enough.

All bundled providers

Every service Hermes can log you into out of the box.

Claude Code

The same skill pattern for Anthropic’s CLI agent.