Programmatic Access: The API Server and IDE Integration (ACP)

Part One: The API Server

The API server exposes Hermes as an OpenAI-compatible HTTP endpoint, which means any frontend that already knows how to talk to the OpenAI API -- Open WebUI, LobeChat, LibreChat, and similar tools -- can talk to Hermes with little to no extra configuration. Critically, this is not a stripped-down endpoint: the agent responds with its full toolset, including terminal access, file operations, web search, and memory.

Enabling It

Add to ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev

Start the gateway, which is also what runs the API server:

hermes gateway

You should see: [API Server] API server listening on http://127.0.0.1:8642

Test it directly with curl:

curl http://localhost:8642/v1/chat/completions 
  -H "Authorization: Bearer change-me-local-dev" 
  -H "Content-Type: application/json" 
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

Available Endpoints

Configuration and Multi-User Setup

Key environment variables: API_SERVER_ENABLED (default false), API_SERVER_PORT (default 8642), API_SERVER_KEY (required bearer token), API_SERVER_CORS_ORIGINS (browser allowlist, comma-separated), API_SERVER_HOST (default 127.0.0.1).

For multiple users, create isolated profiles, each with its own port and key:

hermes profile create alice
hermes profile create bob

A real security note worth taking seriously: the API server provides full access to Hermes' entire toolset, including terminal commands. A bearer token is required for every deployment by design, and CORS is disabled by default -- you have to explicitly opt in to allowing browser-based access from specific origins.

Part Two: ACP and IDE Integration

Separate from the API server, Hermes can also run as an ACP server, letting ACP-compatible editors talk to it directly over stdio and render chat messages, tool activity, file diffs, terminal commands, and approval prompts natively inside the editor.

Install with the ACP extra:

pip install -e '.[acp]'

This makes three equivalent launch commands available: hermes acp, hermes-acp, and python -m acp_adapter. Check your install with hermes acp --version or hermes acp --check.

If you also want browser tools available inside the editor integration: hermes acp --setup-browser [--yes] installs Node.js 22, the agent-browser package, and Playwright Chromium.

Setting Up Each Editor

VS Code: install the ACP Client extension from the marketplace, open the ACP Client panel, select Hermes Agent from the built-in list, and connect. Manual configuration if you need it:

{
  "acp.agents": {
    "Hermes Agent": {
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

Zed: open the Agent Panel, click "Add Agent" or run zed: acp registry, search for Hermes Agent, install, and launch a new thread. You need uv installed for the registry launcher, and credentials already configured via hermes model or ~/.hermes/.env.

JetBrains: use an ACP-compatible plugin and point it at /path/to/hermes-agent/acp_registry.

What ACP Mode Curates Differently

The ACP toolset is deliberately curated for an editor context: file tools (read, write, patch, search), terminal tools, web/browser tools, memory, and code execution -- it excludes things that do not make sense inside an editor, like messaging delivery. Each ACP session tracks its own ID, working directory, selected model, conversation history, and cancel events, scoped to the running server process.

Approval has four options inside ACP, the same shape as approval everywhere else in Hermes: allow once, allow for session (matching calls in the current session only), allow always (permanent allowlist), or deny. "Allow for session" is the useful middle ground -- enough trust to stop re-approving the same call repeatedly, without committing to a permanent allowlist entry.

With your agent now reachable by API, by editor, by messaging platform, and by terminal, the next lesson covers something different: having one agent delegate work to others.