feat: added support for frontier model providers

Author: jahilldev

README.md

@@ -151,7 +151,20 @@ HERMES_PRIMARY_PROVIDER=<provider>
 HERMES_MODEL_BASE_URL=http://localhost:11434/v1   # if using a local endpoint
 ```
 
-For cloud providers, add the relevant API key (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).
+For cloud providers, set each role's provider and add the matching API key to `api/.env` — keys are
+keyed by provider, not by role:
+
+```
+HERMES_PRIMARY_PROVIDER=openai
+HERMES_JUDGE_PROVIDER=anthropic
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Hermes already knows each cloud provider's base URL, so `HERMES_MODEL_BASE_URL` is only needed for
+the `custom` provider (local/self-hosted OpenAI-compatible endpoints). Keys are forwarded by name
+into each agent container, so they never appear in the stored command line; the full list of
+recognised provider env vars is in `api/.env.example`.
 
 **System mode (no Docker):** set in `api/.env`:
 

api/.env.example

@@ -16,66 +16,97 @@ GITHUB_WEBHOOK_SECRET=replace-me
 GITHUB_APP_PRIVATE_KEY=
 GITHUB_APP_PRIVATE_KEY_PATH=./github.pem
 
-# ── Browser (optional — Camofox) ────────────────────────────────────────────
-# Camofox is a self-hosted Firefox-based stealth browser server.
-# When set, all hermes browser tools route through Camofox instead of the
-# cloud providers. Leave empty to disable (hermes falls back to agent-browser).
-# Start Camofox: git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser && make up
-# For SANDBOX_MODE=default the agent container automatically uses host.docker.internal;
-# for SANDBOX_MODE=none set this to http://localhost:9377.
-CAMOFOX_URL=
-
-# ── Hermes Agent CLI ─────────────────────────────────────────────────────────
-# Run `npm run hermes:docker` (repo root) to build the agent image and populate
-# SANDBOX_MODE / DOCKER_AGENT_IMAGE / HERMES_HOME below automatically.HERMES_BIN=hermes
-# HERMES_HOME is the hermes data directory — config, memory notes (MEMORY.md/USER.md),
-# skills, and sessions. api/.hermes/ ships a config.base.yaml template and SOUL.md;
-# a config.yaml is generated from it at startup using the env-var values below.
-# In SANDBOX_MODE=default, MEMORY.md, USER.md, skills/, and config.yaml are bind-mounted
-# into each agent container so settings and learning persist across invocations.
+# ── Sandbox & Hermes runtime ─────────────────────────────────────────────────
+# How and where the Hermes Agent CLI runs. Run `npm run hermes:docker` (repo root) to build
+# the agent image and populate SANDBOX_MODE / DOCKER_AGENT_IMAGE / HERMES_HOME automatically.
+#
+# SANDBOX_MODE:
+#   none    = run hermes as a local subprocess using the system Hermes binary. Set HERMES_HOME
+#             to your existing Hermes data dir (e.g. ~/.hermes) — Hermes reads its own config.yaml
+#             from there. HERMES_PRIMARY_MODEL / HERMES_PRIMARY_PROVIDER / HERMES_TIMEOUT_MS still
+#             apply, passed as CLI flags at invocation time.
+#   default = run hermes inside a Docker container (recommended; requires DOCKER_AGENT_IMAGE).
+SANDBOX_MODE=default
+DOCKER_AGENT_IMAGE=hermes-agent:latest
+# Name/path of the hermes executable used in SANDBOX_MODE=none.
+HERMES_BIN=hermes
+# HERMES_HOME is the hermes data directory — config, memory notes (MEMORY.md/USER.md), skills, and
+# sessions. api/.hermes/ ships a config.base.yaml template and SOUL.md; a config.yaml is generated
+# from it at startup using the env-var values below. In SANDBOX_MODE=default, MEMORY.md, USER.md,
+# skills/, and config.yaml are bind-mounted into each agent container so settings and learning
+# persist across invocations.
 HERMES_HOME=./.hermes
-# Model and provider to use for agent runs. Required in SANDBOX_MODE=default — the
-# Docker container has no pre-existing Hermes config to fall back on, so these must
-# be set or the agent will fail with "No LLM provider configured". In SANDBOX_MODE=none
-# they are optional: Hermes reads its own config.yaml (configured via `hermes setup`).
+
+# ── Models & roles ───────────────────────────────────────────────────────────
+# Each role is a model + provider pair. The provider name selects a credential from the
+# "Provider API keys" section below. Model/provider are passed to Hermes as CLI flags.
+# Primary — used for PLAN and IMPLEMENT/REVISE. Required in SANDBOX_MODE=default: the Docker
+# container has no pre-existing Hermes config to fall back on, so these must be set or the agent
+# fails with "No LLM provider configured". Optional in SANDBOX_MODE=none (Hermes reads config.yaml).
 HERMES_PRIMARY_MODEL=
 HERMES_PRIMARY_PROVIDER=
-# Optional model/provider overrides specifically for review steps. This allows using a more
-# capable or independent model to review than the one used for implementation.
+# Review — optional override for review steps. Lets a more capable or independent model review
+# than the one used for implementation. Falls back to the primary model when unset.
 #HERMES_REVIEW_MODEL=
 #HERMES_REVIEW_PROVIDER=
-# Optional model/provider for Hermes' background auxiliary tasks (context compression, vision
-# analysis, web-extract). Point these at a smaller/faster model so secondary work delegated by
-# the main agent doesn't compete with it — speeding up the overall run. Both are optional and
-# independent; if unset, Hermes uses its own auxiliary defaults ("auto" provider).
+# Auxiliary — optional override for Hermes' background tasks (context compression, vision analysis,
+# web-extract). Point at a smaller/faster model so secondary work delegated by the main agent
+# doesn't compete with it. Both optional and independent; if unset, Hermes uses its own auxiliary
+# defaults ("auto" provider).
 #HERMES_AUXILIARY_MODEL=
 #HERMES_AUXILIARY_PROVIDER=
-# Optional model/provider for the completion judge that decides, after each IMPLEMENT/REVISE
-# pass, whether the plan's acceptance criteria are actually met (and continues the agent with a
-# critique if not). Falls back to the review model, then the primary model. A weak model makes
-# an unreliable judge — prefer a capable one.
+# Judge — optional override for the completion judge that decides, after each IMPLEMENT/REVISE pass,
+# whether the plan's acceptance criteria are met (and continues the agent with a critique if not).
+# Falls back to the review model, then the primary model. A weak model makes an unreliable judge —
+# prefer a capable one.
 #HERMES_JUDGE_MODEL=
 #HERMES_JUDGE_PROVIDER=
-# Hard wall-clock ceiling (ms) for a single Hermes invocation — the process is killed
-# regardless of activity once this elapses. For local inference with large models, increase
-# this; a full implementation cycle can take well over an hour on modest hardware.
+
+# ── Provider API keys (cloud / remote inference) ─────────────────────────────
+# Credentials are keyed by PROVIDER, not by role: each HERMES_*_PROVIDER above names a provider
+# (e.g. openai, anthropic) and Hermes reads that provider's key from the matching standard env var
+# below — and already knows its base URL, so no per-provider URL is needed. (The `custom` provider
+# is the exception: its endpoint is HERMES_MODEL_BASE_URL; local Ollama needs no key at all.) Set
+# only the keys for providers you actually use. In SANDBOX_MODE=default these are forwarded by name
+# into each agent container (the value never appears in the stored command line); in
+# SANDBOX_MODE=none the Hermes subprocess inherits them directly. Recognised: OPENAI_API_KEY,
+# ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY,
+# OPENROUTER_API_KEY, XAI_API_KEY, TOGETHER_API_KEY, FIREWORKS_API_KEY, PERPLEXITY_API_KEY, NOUS_API_KEY.
+#OPENAI_API_KEY=
+#ANTHROPIC_API_KEY=
+
+# ── Inference tuning ─────────────────────────────────────────────────────────
+# Hard wall-clock ceiling (ms) for a single Hermes invocation — the process is killed regardless
+# of activity once this elapses. For local inference with large models, increase this; a full
+# implementation cycle can take well over an hour on modest hardware.
 HERMES_TIMEOUT_MS=7200000
-# Maximum context window size (tokens) passed to Hermes as context_length in config.yaml.
-# Must match the model's actual context window — too large causes OOM on the inference
-# server; too small causes premature compression. Omit to let Hermes use its model default.
+# Maximum context window size (tokens) passed to Hermes as context_length in config.yaml. Must
+# match the model's actual context window — too large causes OOM on the inference server; too small
+# causes premature compression. Omit to let Hermes use its model default.
 HERMES_CONTEXT_LENGTH=131072
-# Fraction of the context window (0–1) at which Hermes compresses older messages to free
-# space. Lower values compress more aggressively; higher values preserve more history at
-# the cost of context pressure. Omit to use the Hermes default (0.5).
+# Fraction of the context window (0–1) at which Hermes compresses older messages to free space.
+# Lower values compress more aggressively; higher values preserve more history at the cost of
+# context pressure. Omit to use the Hermes default (0.5).
 HERMES_COMPRESS_THRESHOLD=0.80
-# OpenAI-compatible base URL for the model provider. In SANDBOX_MODE=default this is
-# automatically rewritten to host.docker.internal so the agent container can reach a
-# local inference server running on the host. Omit to use the Hermes default (Ollama at
-# http://localhost:11434/v1).
+# OpenAI-compatible base URL for the model provider. Only needed for the `custom` provider
+# (local/self-hosted endpoints) — named cloud providers already know their own URL. In
+# SANDBOX_MODE=default this is automatically rewritten to host.docker.internal so the agent
+# container can reach a local inference server running on the host. Omit to use the Hermes default
+# (Ollama at http://localhost:11434/v1).
 HERMES_MODEL_BASE_URL=http://localhost:11434/v1
-# Diagnostic: when true, logs a compact identity line (type/name/model/usage/attribute keys)
-# for every incoming trace span. Use to inspect exactly how Hermes traces compression and
-# other auxiliary calls. Noisy — leave off in normal operation.
+
+# ── Browser (optional — Camofox) ────────────────────────────────────────────
+# Camofox is a self-hosted Firefox-based stealth browser server. When set, all hermes browser tools
+# route through Camofox instead of the cloud providers. Leave empty to disable (hermes falls back to
+# agent-browser). Start Camofox: git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser && make up
+# For SANDBOX_MODE=default the agent container automatically uses host.docker.internal; for
+# SANDBOX_MODE=none set this to http://localhost:9377.
+CAMOFOX_URL=
+
+# ── Observability ────────────────────────────────────────────────────────────
+# Diagnostic: when true, logs a compact identity line (type/name/model/usage/attribute keys) for
+# every incoming trace span. Use to inspect exactly how Hermes traces compression and other
+# auxiliary calls. Noisy — leave off in normal operation.
 #LANGFUSE_DEBUG_SPANS=false
 
 # ── Orchestration policy ─────────────────────────────────────────────────────
@@ -106,29 +137,20 @@ QUEUE_BACKOFF_BASE_MS=15000
 QUEUE_LOCK_TTL_MS=3600000
 
 # ── Workspace / git ──────────────────────────────────────────────────────────
-# Path to the directory where per-job git worktrees are cloned. When running via
-# docker-compose, this is overridden to ${PWD}/workspaces and mounted at that same
-# absolute path inside the container so sibling agent containers (spawned via the
-# Docker socket) can reference workspace directories by the same path the host sees.
+# Path to the directory where per-job git worktrees are cloned. When running via docker-compose,
+# this is overridden to ${PWD}/workspaces and mounted at that same absolute path inside the
+# container so sibling agent containers (spawned via the Docker socket) can reference workspace
+# directories by the same path the host sees.
 WORKSPACE_ROOT=./.workspaces
 GIT_AUTHOR_NAME=Hermes Agent
 GIT_AUTHOR_EMAIL=hermes@users.noreply.github.com
 # Branch name template; {issue} is replaced with the issue number.
 BRANCH_PREFIX=hermes/issue-
-# Optional dedicated SSH deploy key for cloning/pushing DASHBOARD-origin jobs (created from
-# the UI) against an SSH remote. Leave UNSET to use the host's own SSH setup (ssh-agent,
-# ~/.ssh/config, default keys) exactly as a normal `git clone git@…` would — this is the
-# usual case when the orchestrator runs on a host that already has repo access. Set it only
-# to force an isolated key (it then ignores the host agent via IdentitiesOnly). Powerful — it
-# can push to any repo it's authorised for; mount it read-only and never expose it to the
-# agent container (git runs on the orchestrator host, not the agent sandbox).
+# Optional dedicated SSH deploy key for cloning/pushing DASHBOARD-origin jobs (created from the UI)
+# against an SSH remote. Leave UNSET to use the host's own SSH setup (ssh-agent, ~/.ssh/config,
+# default keys) exactly as a normal `git clone git@…` would — this is the usual case when the
+# orchestrator runs on a host that already has repo access. Set it only to force an isolated key
+# (it then ignores the host agent via IdentitiesOnly). Powerful — it can push to any repo it's
+# authorised for; mount it read-only and never expose it to the agent container (git runs on the
+# orchestrator host, not the agent sandbox).
 #GIT_SSH_KEY_PATH=/home/youruser/.ssh/olympian_deploy_key
-
-# ── Sandbox ──────────────────────────────────────────────────────────────────
-# none = run hermes as a local subprocess using the system Hermes binary.
-#   Set HERMES_HOME to your existing Hermes data directory (e.g. ~/.hermes) — Hermes
-#   reads its own config.yaml from there. HERMES_PRIMARY_MODEL / HERMES_PRIMARY_PROVIDER
-#   / HERMES_TIMEOUT_MS still apply as they are passed as CLI flags at invocation time.
-# default = run hermes inside a Docker container (recommended; requires DOCKER_AGENT_IMAGE).
-SANDBOX_MODE=default
-DOCKER_AGENT_IMAGE=hermes-agent:latest

api/src/agent/agent.utility.spec.ts

@@ -158,6 +158,51 @@ describe('buildAgentSpec', () => {
       expect.arrayContaining(['--model', 'anthropic/claude-sonnet-4.6', '--provider', 'anthropic']),
     );
   });
+
+  it('forwards set provider API keys into the container by name only (no secret in args)', () => {
+    const prev = process.env.OPENAI_API_KEY;
+    process.env.OPENAI_API_KEY = 'sk-secret-value';
+    try {
+      const spec = buildAgentSpec({
+        sandboxMode: 'default',
+        hermesBin: 'hermes',
+        dockerImage: 'img',
+        cwd: '/w',
+        prompt: 'test prompt',
+      });
+      // name is forwarded...
+      const idx = spec.args.indexOf('OPENAI_API_KEY');
+      expect(idx).toBeGreaterThan(-1);
+      expect(spec.args[idx - 1]).toBe('--env');
+      // ...but the value never appears in the args (which get persisted to AgentRun.command).
+      expect(spec.args.join(' ')).not.toContain('sk-secret-value');
+    } finally {
+      if (prev === undefined) {
+        delete process.env.OPENAI_API_KEY;
+      } else {
+        process.env.OPENAI_API_KEY = prev;
+      }
+    }
+  });
+
+  it('does not forward provider API keys that are unset', () => {
+    const prev = process.env.GROQ_API_KEY;
+    delete process.env.GROQ_API_KEY;
+    try {
+      const spec = buildAgentSpec({
+        sandboxMode: 'default',
+        hermesBin: 'hermes',
+        dockerImage: 'img',
+        cwd: '/w',
+        prompt: 'test prompt',
+      });
+      expect(spec.args).not.toContain('GROQ_API_KEY');
+    } finally {
+      if (prev !== undefined) {
+        process.env.GROQ_API_KEY = prev;
+      }
+    }
+  });
 });
 
 describe('generateHermesConfig auxiliary model', () => {

api/src/agent/agent.utility.ts

@@ -11,6 +11,36 @@ import { type LangfuseEvent } from '../langfuse/langfuse.model.js';
 const HERMES_CONTAINER_HOME = '/root/.hermes';
 const CONTAINER_WORKDIR = '/workspace';
 
+/**
+ * Provider credential env vars forwarded into the agent container (SANDBOX_MODE=default).
+ *
+ * A model role selects a provider via `--provider <name>` (e.g. HERMES_JUDGE_PROVIDER=anthropic);
+ * Hermes then reads that provider's API key from the standard env var below and already knows the
+ * provider's base URL, so no per-provider base_url config is needed (the `custom` provider is the
+ * exception — its endpoint comes from HERMES_MODEL_BASE_URL). Forwarding every present key into
+ * each container also covers Hermes' background auxiliary tasks (compression/vision/web-extract),
+ * which run in-process under the primary and so need their provider's key in the same container.
+ *
+ * Forwarded by NAME ONLY (`--env OPENAI_API_KEY`) so the value is pulled from the orchestrator's
+ * own environment by the docker CLI and never lands in the args array — which is persisted verbatim
+ * to AgentRun.command. Add new providers here as needed.
+ */
+export const PROVIDER_CREDENTIAL_ENV = [
+  'OPENAI_API_KEY',
+  'ANTHROPIC_API_KEY',
+  'GEMINI_API_KEY',
+  'GOOGLE_API_KEY',
+  'GROQ_API_KEY',
+  'MISTRAL_API_KEY',
+  'DEEPSEEK_API_KEY',
+  'OPENROUTER_API_KEY',
+  'XAI_API_KEY',
+  'TOGETHER_API_KEY',
+  'FIREWORKS_API_KEY',
+  'PERPLEXITY_API_KEY',
+  'NOUS_API_KEY',
+] as const;
+
 export interface AgentSpecParams {
   sandboxMode: 'none' | 'default';
   hermesBin: string;
@@ -124,6 +154,15 @@ export function buildAgentSpec(p: AgentSpecParams): SpawnSpec {
       `HERMES_LANGFUSE_BASE_URL=http://host.docker.internal:${langfusePort}/langfuse`,
     );
 
+    // Forward provider API keys (by name only) so the role's selected provider can
+    // authenticate. Name-only keeps the secret out of args (persisted to AgentRun.command);
+    // docker resolves the value from this process's env at spawn time.
+    for (const name of PROVIDER_CREDENTIAL_ENV) {
+      if (process.env[name]) {
+        args.push('--env', name);
+      }
+    }
+
     const containerName = `olympian-agent-${randomUUID()}`;
 
     args.push('--name', containerName);