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

# Hermes Agent

> Connect Hermes Agent to Prem API through the local Confidential Proxy.

Hermes Agent supports named custom providers that use the OpenAI Chat Completions protocol. Point one of those providers at Prem's local Confidential Proxy.

<Warning>
  Do not configure Prem under Hermes' `openai-api` provider. That provider can select the OpenAI Responses API, which the Confidential Proxy does not expose. Use a named custom provider with `transport: chat_completions`.
</Warning>

<Tabs>
  <Tab title="Confidential API">
    Use the local Confidential Proxy for sensitive model traffic. [Go to the confidential setup](#confidential-api).
  </Tab>

  <Tab title="Router (Beta)">
    <Badge color="blue">Beta</Badge>

    Use Router for its broader model catalog with non-sensitive data. [Go to the Router setup](#router).
  </Tab>
</Tabs>

## Confidential API

## How the connection works

```mermaid theme={"system"}
flowchart TB
    subgraph Local["Your machine: plaintext is available"]
        H["Hermes Agent"] -->|"Chat Completions"| P["Confidential Proxy<br/>127.0.0.1:8787/v1"]
        T["Terminal, files, skills, and tools"] <--> H
    end

    P -->|"Encrypt before network egress"| G["Prem API Gateway<br/>ciphertext and metadata"]
    G -->|"Encrypted request"| E["Prem confidential runtime<br/>decrypt, infer, encrypt"]
    E -.->|"Encrypted response"| P
    P -.->|"OpenAI-compatible response"| H
```

## Before you start

You need:

* Hermes Agent installed. See the [Hermes Agent repository](https://github.com/NousResearch/hermes-agent).
* A Prem API key. See [API Keys](/api-keys).
* A 32-byte client KEK encoded as 64 hexadecimal characters.
* The current Prem gateway and enclave endpoints.
* A chat model returned by the Prem model-list endpoint.

Check the installed version:

```bash theme={"system"}
hermes --version
```

The configuration below has been exercised with Hermes Agent `0.20.0` using a one-shot response and a local file-reading tool call.

## 1. Set your secrets

```bash theme={"system"}
export PREM_API_KEY="your-prem-api-key"
export CLIENT_KEK="your-64-character-hex-kek"
export PROXY_URL="https://gateway.prem.io"
export ENCLAVE_URL="https://conf-engine.prem.io"
```

Generate the KEK once if you do not have one:

```bash theme={"system"}
openssl rand -hex 32
```

Keep `PREM_API_KEY` out of `config.yaml`. Hermes resolves it from the environment variable named by `key_env`.

## 2. Start the Confidential Proxy

```bash theme={"system"}
npx -p @premai/api-sdk@1.0.59 confidential-proxy \
  --host 127.0.0.1 \
  --port 8787 \
  --compat openai \
  --kek "$CLIENT_KEK"
```

<Warning>
  Do not use `--no-attest`. Keep attestation enabled for confidential inference.
</Warning>

## 3. Select an enabled model

```bash theme={"system"}
curl http://127.0.0.1:8787/v1/models \
  -H "Authorization: Bearer $PREM_API_KEY"
```

Use a returned `id`. This example uses `qwen36-27b`:

```bash theme={"system"}
curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Authorization: Bearer $PREM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen36-27b",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "stream": false
  }'
```

Do not continue until this request succeeds.

## 4. Configure Hermes

Add this provider to `~/.hermes/config.yaml`:

```yaml theme={"system"}
providers:
  prem-confidential:
    api: http://127.0.0.1:8787/v1
    key_env: PREM_API_KEY
    transport: chat_completions
    default_model: qwen36-27b
    models:
      qwen36-27b:
        context_length: 131072

model:
  default: qwen36-27b
  provider: custom:prem-confidential
  context_length: 131072
```

Replace the model ID and context length when you choose another enabled model. Keep `transport: chat_completions` explicit.

The keyed `providers` format is Hermes' current custom-provider schema. See the [Hermes custom-provider documentation](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/integrations/providers.md#named-custom-providers).

Check the configuration:

```bash theme={"system"}
hermes config check
```

## 5. Run Hermes

Start with a bounded one-shot request:

```bash theme={"system"}
hermes --oneshot "Reply with exactly OK. Do not use tools."
```

Then start an interactive session:

```bash theme={"system"}
hermes chat
```

Hermes can stream responses and perform tool calls through this provider. The model request and tool-call response use the encrypted model channel. Hermes runs the selected tool on your machine, then sends any resulting context in a later encrypted model request.

## Tool, memory, and gateway boundary

| Component                                          | Plaintext access                  | Notes                                                          |
| -------------------------------------------------- | --------------------------------- | -------------------------------------------------------------- |
| Hermes Agent                                       | Yes                               | Reads prompts, memory, rules, workspace data, and tool results |
| Confidential Proxy                                 | Yes, locally                      | Encrypts model requests and decrypts responses                 |
| Prem API Gateway                                   | No content access                 | Receives ciphertext and operational metadata                   |
| Prem confidential runtime                          | Yes, inside the protected runtime | Runs inference and encrypts the result                         |
| Shell, skills, messaging gateways, and MCP servers | Depends on the integration        | Remain outside the Prem confidential boundary                  |

Hermes can connect to messaging channels and run scheduled work. Review sender allowlists, approval rules, toolsets, hooks, and outbound network access before enabling those surfaces.

## Agent limits

The encrypted chat endpoint permits one active stream for each API key. Parallel Hermes sessions, delegation, fallback attempts, or messaging workers that share one key can receive `429` responses.

Begin with one session and no delegation. Serialize turns or use a separate Prem API key per concurrent worker. Do not configure a non-Prem fallback if every model turn must use Prem's encrypted path.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Hermes calls /v1/responses">
    The session is using the wrong provider. Set `model.provider` to `custom:prem-confidential` and keep `transport: chat_completions` in the named provider.
  </Accordion>

  <Accordion title="Hermes reports a missing API key">
    Export `PREM_API_KEY` in the process that starts Hermes. Confirm that `key_env` has the exact same name.
  </Accordion>

  <Accordion title="The API returns model not found">
    Call `/v1/models`. Use a returned ID in `default_model`, `providers.prem-confidential.models`, and `model.default`.
  </Accordion>

  <Accordion title="A tool can read more than expected">
    Limit Hermes toolsets, workspace access, approval settings, hooks, and MCP servers. Model-path confidentiality does not restrict local tool permissions.
  </Accordion>

  <Accordion title="The API returns 429">
    Wait for the active stream to finish. Reduce delegation and parallel workers or use distinct API keys.
  </Accordion>
</AccordionGroup>

## Frequently asked questions

### Is Hermes itself running inside the enclave?

No. Hermes runs locally. The Prem confidential boundary starts after the local proxy encrypts a supported model request.

### Why not use `OPENAI_BASE_URL` with the built-in OpenAI provider?

That route can use `/v1/responses`. The named custom provider fixes the protocol to `/v1/chat/completions`, which the Confidential Proxy supports.

### Can Hermes tools use the encrypted connection?

The model can request a tool through the encrypted model channel. Hermes executes the tool outside the enclave. A tool's own network traffic does not pass through Prem unless you configure that tool separately.

### Can Hermes use fallback providers?

Yes, but a non-Prem fallback leaves the Prem inference path. Omit those fallbacks when the encrypted route is a requirement.

## Router

<Badge color="blue">Beta</Badge>

<Warning>
  Router is not confidential. Use this path only for non-sensitive prompts,
  memory, workspace context, and tool results.
</Warning>

Hermes uses Router through a second named provider.

```bash theme={"system"}
export PREM_ROUTER_API_KEY="your-router-api-key"
```

Confirm that `kimi-k3` appears in `GET /v1/models` for this key. Otherwise, use
an exact returned model ID. See [Router models](/router/models).

Use the `prem-router` configuration in the [Router Hermes configuration](/router/integrations#hermes-agent):

| Field            | Value                       |
| ---------------- | --------------------------- |
| `api`            | `https://router.prem.io/v1` |
| `key_env`        | `PREM_ROUTER_API_KEY`       |
| `transport`      | `chat_completions`          |
| `default_model`  | `kimi-k3`                   |
| `model.provider` | `custom:prem-router`        |

Run `hermes config check` after switching. Do not reuse `PREM_API_KEY` or the client KEK for Router.

## Related

<CardGroup cols={2}>
  <Card title="Confidential Proxy" icon="server" href="/confidential-proxy" arrow="true">
    Review proxy modes, routes, keys, and daemon controls.
  </Card>

  <Card title="OpenAI-compatible clients" icon="code" href="/guides/openai-compatible-clients" arrow="true">
    Understand the protocol used by Hermes.
  </Card>

  <Card title="Agents & Automation" icon="robot" href="/agents" arrow="true">
    Review concurrency, retries, and unattended operation.
  </Card>

  <Card title="Security Model" icon="shield-halved" href="/security-model" arrow="true">
    Review the protected and unprotected parts of the flow.
  </Card>
</CardGroup>