hermes-headroom: model tool for Hermes Agent

Installer that routes Hermes Agent traffic through the Headroom compression proxy via OpenRouter

What hermes-headroom does

Unlike a per-session launcher, this sets things up once and globally. Hermes reads OPENROUTER_BASE_URL from ~/.hermes/.env and applies it to every process that uses the openrouter provider, so the gateway, all profiles, cron jobs, kanban workers, delegated subagents and the plain CLI all pass through the Headroom proxy without config.yaml or per-profile edits. The README says compression typically cuts 60 to 95 percent of tokens for the same answers.

The install script creates a systemd user service, headroom-proxy.service, running headroom proxy --backend openrouter on 127.0.0.1, adds a clearly marked block to ~/.hermes/.env, and writes a drop-in so the Hermes gateway starts after the proxy. An optional ENABLE_MCP=1 setting adds Headroom's retrieve tool to the default config.yaml after a timestamped backup. The default model is DeepSeek V4 Flash with a 1,000,000-token context, and uninstall.sh reverses every change. Codex and Claude Code subagents call their own endpoints and are not covered.

Key features

Persistent systemd user service running the Headroom proxy
One OPENROUTER_BASE_URL setting that covers gateway, profiles, cron, kanban and subagents
.env settings for model, port, context length and optional MCP tools
Boot-ordering drop-in so the gateway starts after the proxy
uninstall.sh that reverses the changes and restores a prior OPENROUTER_BASE_URL
headroom perf command for token and cost savings

When to use it

Cutting token use of long-running Hermes gateway agents on OpenRouter
Compressing tool output and logs for cron and kanban workers
Checking tokens and cost saved over the last 24 hours

Who it is for: Hermes Agent operators on Linux with systemd who use OpenRouter and want lower token use.

How it fits with Hermes Agent

Built for Hermes Agent. It works by setting the OPENROUTER_BASE_URL variable that Hermes reads from ~/.hermes/.env.

How to install hermes-headroom

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

./setup.sh
./install.sh
hermes gateway restart

Requirements: Hermes Agent with the hermes CLI on PATH, uv, and an OpenRouter API key; Hermes needs a context window of at least 64000 for agent use

Note: Only traffic routed through OpenRouter is compressed, and Codex or Claude Code subagents that call their own endpoints bypass the proxy.

FAQ

What is hermes-headroom?

hermes-headroom is a set of install scripts that put the Headroom compression proxy in front of Hermes Agent persistently and globally, using OpenRouter as the model provider.

What do I need to run hermes-headroom?

You need Hermes Agent with the hermes CLI on your PATH, uv, and an OpenRouter API key. The default model is DeepSeek V4 Flash, and Hermes needs a context window of at least 64000 tokens.

Does hermes-headroom compress Codex or Claude Code subagent traffic?

No. It only wraps traffic that Hermes routes through OpenRouter. Codex and Claude Code subagents call their own endpoints, so they need a separate Headroom proxy or headroom wrap.