hermes-opencode-acp — OpenCode as a Hermes Agent provider

news · 2026-09-22

OpenCode's free tier now only works from inside OpenCode

Direct HTTP calls to the Zen free tier are rejected server-side — verified live: FreeTierError: OpenCode's free tier can only be used from within OpenCode. That kills Hermes's built-in opencode-free path and any direct-HTTP free-model plugin. This project keeps working because it runs inside OpenCode: Hermes drives a real opencode acp subprocess, so free models keep flowing. Same week: v1.2.0 drops the Hermes-core patch entirely — user-dir plugin install, survives hermes update.

what you get

Features

OpenCode is the backend, so you inherit its agentic loop — model selection, tool use, plugin fallbacks — while Hermes drives the ACP wire.

catalogFull OpenCode catalog — 200+ models (Anthropic, OpenAI, Google, DeepSeek, Kimi…). No per-provider API keys; OpenCode handles auth.

sessionsPersistent process + session per (command, args, cwd). No respawn per turn, no context loss.

model switchSwitching models reuses the same session — applied in place via session/set_config_option, prior context recalled.

tool callsOpenCode's native <tool_call> XML parsed back into OpenAI function-call shape for Hermes's tool loop.

model pickingACP-native catalog probe — /model shows what the opencode acp server actually validates, not a static list.

fallbacksWorks in Hermes's fallback chain — when the primary provider rate-limits, fall back through OpenCode models.

free tierOpenCode Go credits cover free models — run Hermes on free, fall back to paid when exhausted.

file safetyfs/read_text_file + fs/write_text_file routed through Hermes's file-safety and redaction layers.

get going

Quick start

Install OpenCode, run the plugin installer, enable it, then pick a model. No Hermes-core patch — update-safe.

install + configure

# 1. OpenCode CLI + auth (skip if already installed)
npm i -g opencode-ai@latest
opencode auth login

# 2. Clone this repo
git clone https://github.com/jovylle/hermes-opencode-acp.git
cd hermes-opencode-acp

# 3. Install + enable the plugin (idempotent, update-safe)
./install-plugin.sh
hermes plugins enable opencode-acp-provider
hermes plugins validate ~/.hermes/plugins/model-providers/opencode-acp

# 4. Pick a model — shows the live OpenCode catalog
hermes model
# OpenCode → OpenCode ACP → pick (e.g. opencode/deepseek-v4-flash)

# 5. Restart and use
hermes gateway restart
hermes chat

configuration

Point Hermes at OpenCode

Either run hermes model and pick from the live catalog, or set it directly.

config.yaml

model:
  provider: opencode-acp
  model: opencode/deepseek-v4-flash
  base_url: acp://opencode
  api_mode: chat_completions

# fallback chain — free models first, paid when exhausted
fallback_providers:
  - provider: opencode-acp
    model: opencode/mimo-v2.5-free
    base_url: acp://opencode
  - provider: opencode-acp
    model: opencode/kimi-k2.6
    base_url: acp://opencode

upstream watch

We're tracking hermes-agent's own ACP plans

Hermes core is planning a generalized ACP client — and OpenCode is already on their list.

▲ NousResearch/hermes-agent#5257 — "Generalized ACP client for multi-agent CLI orchestration"

Core proposes a generic ACPClient + registry of 14 agents (Claude Code, Codex, Gemini, Cursor, Copilot, OpenCode, Kimi, Qwen…). When it lands, this plugin's client retires in favor of core and config stays compatible — provider: opencode-acp keeps working as-is. The migration checklist lives in UPSTREAM.md.