# Hermes Agents

> Create, ground, chat with, and manage hosted Hermes agents from the terminal — divinci hermes create/list/get/update/chat/key/delete.

Manage [hosted Hermes agents](/server/hermes-agents/) — isolated
NousResearch Hermes containers on Divinci infrastructure — without leaving your
terminal. Every command supports the global `--json` flag for scripting and
`--workspace <id>` to override the active workspace.

## Create

```bash
# Platform model (Divinci-paid, no key needed) — the default
divinci hermes create --title "Support Bot"

# Pick a model explicitly
divinci hermes create --title "Llama Bot" \
  --model "cloudflare/@cf/meta/llama-3.3-70b-instruct-fp8-fast"

# Bring your own key
divinci hermes create --title "Claude Agent" \
  --model "anthropic/claude-sonnet-4-5" \
  --provider anthropic --provider-api-key "$ANTHROPIC_API_KEY"

# Ground every turn in a Release's knowledge base (RAG)
divinci hermes create --title "Docs Agent" --release <releaseId>
```

Also accepts `--system-prompt` (persona) and `--description`.

## List and inspect

```bash
divinci hermes list

divinci hermes get <agentId>
# → model, status (provisioned | active | stopped), linked releaseId,
#   BYOK provider + hasProviderApiKey, and the hsk- proxy key
```

## Update

Partial update — only the flags you pass are touched:

```bash
divinci hermes update <agentId> --model "vertex_ai/gemini-2.5-pro"
divinci hermes update <agentId> --system-prompt "New persona"
divinci hermes update <agentId> --disable        # reject chat with 403
divinci hermes update <agentId> --enable

# RAG grounding
divinci hermes update <agentId> --release <releaseId>
divinci hermes update <agentId> --clear-release

# BYOK key rotation (encrypted server-side, never echoed back)
divinci hermes update <agentId> --provider anthropic --provider-api-key "$NEW_KEY"
divinci hermes update <agentId> --clear-provider-key   # revert to platform billing
```

## Chat

```bash
divinci hermes chat <agentId> "Summarize our refund policy."
```

Prints the agent's reply. Each successful turn is metered to the workspace
wallet.

<Aside type="note" title="Cold starts are handled for you">
  A sleeping container cold-boots on the first turn (typically 30–60s). If the
  API returns <code>503 agent_warming</code>, the CLI waits ~30 seconds and
  retries once automatically — you'll see an "Agent is cold-starting" spinner.
</Aside>

## Proxy key

```bash
divinci hermes key <agentId>            # print the hsk- key + connection hint
divinci hermes key <agentId> --rotate   # mint a new key, revoking the old one
```

Drop the key into any OpenAI-compatible client:

```bash
export OPENAI_BASE_URL="https://api.divinci.app/api/v1/hermes-proxy"
export OPENAI_API_KEY="hsk-your-agent-proxy-key"
```

## Delete

```bash
divinci hermes delete <agentId>   # stops the container and removes the record
```

<Aside type="tip" title="Environments behind Cloudflare Access">
  If your API host is fronted by Cloudflare Access (e.g. a staging
  environment), give the CLI the service-token headers via
  <code>DIVINCI_EXTRA_HEADERS</code>:

  ```bash
  export DIVINCI_EXTRA_HEADERS='{"CF-Access-Client-Id":"…","CF-Access-Client-Secret":"…"}'
  ```

  The headers are sent on every request in addition to your normal Divinci
  auth. Malformed JSON is a hard error so a broken value can't silently turn
  into an opaque edge 403.
</Aside>