> ## Documentation Index
> Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Use authsome from Hermes Agent via the bundled skill. One login, then Hermes calls every provider with a fresh token from the local vault.

[Hermes Agent](https://github.com/NousResearch/hermes-agent) is the self-improving agent runtime from [Nous Research](https://nousresearch.com). It installs skills following the [agentskills.io](https://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.

<Note>
  **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.
</Note>

## Install the skill

Authsome's skill installs into Hermes with a single command:

```bash theme={null}
hermes skills install agentrhq/authsome/skills/authsome
```

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:

```text theme={null}
Use the authsome skill to log me into GitHub.
```

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:

<Steps>
  <Step title="Ask Hermes what's already configured">
    ```text theme={null}
    Use authsome to show me which providers are connected.
    ```

    Hermes runs `authsome list` and reports which providers are bundled, configured, and connected.
  </Step>

  <Step title="Log in to a provider">
    ```text theme={null}
    Log in to GitHub via authsome.
    ```

    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.
  </Step>

  <Step title="Use the connection">
    ```text theme={null}
    Use authsome to fetch my last 5 GitHub notifications.
    ```

    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.
  </Step>
</Steps>

## Common prompts

| Prompt                                                    | What Hermes runs                          |
| --------------------------------------------------------- | ----------------------------------------- |
| "Log me in to GitHub via authsome."                       | `authsome login github`                   |
| "Use the Resend API key from authsome to send an email."  | `authsome run -- python <script>`         |
| "Switch the active GitHub connection to my work account." | `authsome login github --connection work` |
| "Show me which providers are connected."                  | `authsome list`                           |
| "Revoke my OpenAI key."                                   | `authsome revoke openai`                  |
| "Add a custom provider for Acme CRM."                     | `authsome register ./acmecrm.json`        |

## 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:

| Pattern                   | Token visible in                                           |
| ------------------------- | ---------------------------------------------------------- |
| `export GITHUB_TOKEN=...` | `ps`, `/proc/<pid>/environ`, shell history, subprocess env |
| `.env` file in the repo   | The repo, backups, git history if committed by accident    |
| Manual paste into Hermes  | Hermes's transcript and skill log                          |
| `authsome run -- ...`     | None of the above                                          |

`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:

```text theme={null}
Log me into GitHub as my work account.
```

Hermes runs:

```bash theme={null}
authsome login github --connection work
```

Read it back:

```text theme={null}
Use the work GitHub connection to open a PR.
```

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:

```bash theme={null}
authsome run -- python my_agent.py
```

Hermes can also drop below the CLI into the Python library when it needs explicit per-call control:

```bash theme={null}
authsome run -- python my_agent.py
# or: eval "$(authsome export <provider> --format env)"
```

See [Run agents with the proxy](/docs/guides/run-agents-with-proxy) and [Python library](/docs/reference/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](/docs/troubleshooting/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](/docs/troubleshooting/oauth-callbacks) and [Token refresh](/docs/troubleshooting/token-refresh).

## What's next

<Columns cols={2}>
  <Card title="Run agents with the proxy" icon="shield-halved" href="/docs/guides/run-agents-with-proxy">
    The proxy injection model the skill uses under the hood.
  </Card>

  <Card title="Python library" icon="code" href="/docs/reference/python-library">
    Use `authsome export` or the daemon HTTP API when the proxy is not enough.
  </Card>

  <Card title="All bundled providers" icon="plug" href="/docs/reference/bundled-providers">
    Every service Hermes can log you into out of the box.
  </Card>

  <Card title="Claude Code" icon="robot" href="/docs/integrations/agents/claude-code">
    The same skill pattern for Anthropic's CLI agent.
  </Card>
</Columns>