Hermes Agent OS Setup Guide

Hermes Agent OS Setup Guide

This package is a local-first/self-hosted Agent OS. It ships the Hermes purple dashboard, Express runtime API, real @elizaos/core runtime dependency, vendored upstream Firecrawl Open Agent Builder source, upstream builder replay overlays, guided first-run setup, internal Kernel API, provider router, scheduler, local memory, skill registry, local self modules, logs, workflow storage, Docker deployment files, Docker smoke verification, and clean export audit.

It does not ship API keys, private workflows, logs, Hermes profiles, local paths, or fake connected statuses.

Local Install

unzip "Hermes Owner Hunter Workflow.zip" -d Hermes-Agent-OS
cd Hermes-Agent-OS
npm install
cp .env.example .env
npm test
npm run build
npm start

Open:

http://localhost:4173

Verify:

curl http://localhost:4173/api/health
curl http://localhost:4173/api/os/kernel
curl http://localhost:4173/api/os/audit
curl http://localhost:4173/api/setup
curl http://localhost:4173/api/setup/providers
curl http://localhost:4173/api/router/status
curl http://localhost:4173/api/usage
curl http://localhost:4173/api/scheduler
curl http://localhost:4173/api/memory
curl http://localhost:4173/api/skills

First-Run Setup

Open the dashboard, then go to Setup.

Choose:

• local for laptop/local machine.
• docker for Docker Compose.
• vps for a public server.

The setup page checks:

• runtime load
• selected install mode
• at least one model provider
• guided provider fields and provider-specific tests
• Claude Code-style local/open routing
• Firecrawl builder execution config
• starter workflow run

Guided provider setup supports:

• Ollama: OLLAMA_HOST, health test, model inventory, and dry-run ollama pull <model> helper
• OpenRouter: OPENROUTER_API_KEY, optional OPENROUTER_MANAGEMENT_KEY, model override, and model-list health test
• MiniMax: MINIMAX_API_KEY, model override, and model-list health test
• OpenAI: OPENAI_API_KEY, optional OPENAI_ADMIN_KEY, model override, and model-list health test
• Anthropic: ANTHROPIC_API_KEY, model override, and model-list health test
• Gemini: GEMINI_API_KEY, model override, and model-list health test
• Firecrawl: FIRECRAWL_API_KEY readiness check
• Convex: NEXT_PUBLIC_CONVEX_URL readiness check
• Clerk: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, and CLERK_JWT_ISSUER_DOMAIN readiness check

Provider setup APIs:

curl http://localhost:4173/api/setup/providers
curl -X POST http://localhost:4173/api/setup/providers/ollama/configure \
  -H 'Content-Type: application/json' \
  -d '{"fields":{"OLLAMA_HOST":"http://127.0.0.1:11434"},"model":"llama3.1"}'
curl -X POST http://localhost:4173/api/setup/providers/ollama/test
curl http://localhost:4173/api/setup/providers/ollama/models
curl -X POST http://localhost:4173/api/setup/providers/ollama/pull-model \
  -H 'Content-Type: application/json' \
  -d '{"model":"llama3.1"}'

The model pull helper is dry-run unless HERMES_AGENT_OS_ENABLE_INSTALL=1 and execute:true are both set.

Builder execution is optional for setup completion because Convex, Clerk, Firecrawl, and LLM keys are external accounts.

Internal Runtime Check

The dashboard no longer exposes a Kernel page. Use the internal Kernel API when you need to prove the Agent OS subsystems from one sanitized endpoint:

• runtime core
• module registry
• provider router
• workflow engine
• scheduler
• memory
• skill registry
• usage ledger
• Firecrawl builder adapter
• security/export safety

API check:

curl http://localhost:4173/api/os/kernel

The workflow engine runs graph edges, branch labels/source handles/default edges, parallel fan-out from non-routing nodes, while-loop iteration limits, max-step loop guards, approval resume, replayable run events, and a visual replay graph derived from saved workflow/run state. Provider Router stays config_required until a user-owned provider key or local Ollama host is configured.

Provider Router

Open Provider Router.

Supported routes:

• Ollama via OLLAMA_HOST
• OpenRouter via OPENROUTER_API_KEY
• MiniMax via MINIMAX_API_KEY
• OpenAI via OPENAI_API_KEY
• Anthropic via ANTHROPIC_API_KEY
• Gemini via GEMINI_API_KEY

Optional billing reconciliation uses separate keys where providers require them:

• OpenRouter account credits via OPENROUTER_MANAGEMENT_KEY
• OpenAI organization costs via OPENAI_ADMIN_KEY

The router is dry-run by default. Real execution requires:

HERMES_AGENT_OS_ENABLE_EXEC=1

and requests must pass dryRun=false.

The “Free Claude Code” card is honest: it means Claude Code-style routing through user-owned/local/open providers such as Ollama, OpenRouter, or MiniMax. It does not provide free Anthropic Claude access.

Structured Local CLI Adapters

Open Claude Code, Codex, OpenCode, or OpenClaw.

These modules are dry-run-first. Real CLI execution requires both:

HERMES_AGENT_OS_ENABLE_EXEC=1

and an explicit request payload:

{ "dryRun": false }

Connection fields:

• Claude Code: CLAUDE_CODE_PATH, CLAUDE_CLI_ARGS, CLAUDE_WORKSPACE, CLAUDE_TIMEOUT_MS
• Codex: CODEX_CLI_PATH, CODEX_CLI_ARGS, CODEX_WORKSPACE, CODEX_TIMEOUT_MS
• OpenClaw: OPENCLAW_CLI_PATH, OPENCLAW_CLI_ARGS, OPENCLAW_WORKSPACE, OPENCLAW_TIMEOUT_MS
• OpenCode: OPENCODE_CLI_PATH, OPENCODE_CLI_ARGS, OPENCODE_WORKSPACE, OPENCODE_TIMEOUT_MS

*_CLI_ARGS may include {{message}}. If no args template is configured, Hermes sends the prompt as one CLI argument. *_WORKSPACE sets the allowed working directory; request workspace overrides outside that directory are rejected before the CLI starts. *_TIMEOUT_MS is clamped between 1000 and 300000 ms.

API check:

curl -X POST http://localhost:4173/api/modules/codex/run \
  -H 'Content-Type: application/json' \
  -d '{"message":"hello from setup","dryRun":true}'

Trusted local execution check, only after setting HERMES_AGENT_OS_ENABLE_EXEC=1 and configuring a real local CLI path:

curl -X POST http://localhost:4173/api/modules/codex/run \
  -H 'Content-Type: application/json' \
  -d '{"message":"hello from setup","dryRun":false}'

The run response includes execution.adapterId, exitCode, durationMs, stdoutBytes, stderrBytes, and redacted stdout/stderr. Raw configured paths, home paths, and token-like secrets are not returned.

Health checks do not run completions. They probe model-list or local tags endpoints:

• Ollama: /api/tags
• OpenRouter: /api/v1/models
• MiniMax: /v1/models
• OpenAI: /v1/models
• Anthropic: /v1/models
• Gemini: /v1beta/models

API checks:

curl http://localhost:4173/api/router/status
curl http://localhost:4173/api/router
curl http://localhost:4173/api/router/health
curl 'http://localhost:4173/api/router/health?provider=ollama'

Usage Credits

Open Usage Credits.

Provider Router records usage automatically:

• dry-run dispatches create planned records
• real executions estimate tokens and spend
• daily/monthly limits can block execution before a provider call
• warning threshold flags near-budget usage
• manual records can be added for outside spend
• CSV/JSON provider invoice exports can be previewed and imported for providers without supported billing APIs

API checks:

curl http://localhost:4173/api/usage
curl http://localhost:4173/api/usage/reconciliation
curl -X POST http://localhost:4173/api/usage/budget \
  -H 'Content-Type: application/json' \
  -d '{"dailyLimit":1,"monthlyLimit":20,"warningThreshold":0.8}'

Provider Billing Reconciliation

Open Usage Credits and use Reconcile billing.

Supported provider billing sources:

• OpenRouter key usage: configure OPENROUTER_API_KEY
• OpenRouter account credits: configure OPENROUTER_MANAGEMENT_KEY
• OpenAI organization costs: configure OPENAI_ADMIN_KEY

Unsupported API billing sources are still shown honestly:

• Ollama is local and has no provider invoice
• Anthropic, Gemini, MiniMax, Firecrawl, and local infrastructure invoices can use Billing import rather than fake API reconciliation

Run all reconciliation sources:

curl -X POST http://localhost:4173/api/usage/reconciliation/run \
  -H 'Content-Type: application/json' \
  -d '{"provider":"all"}'

Run one source:

curl -X POST http://localhost:4173/api/usage/reconciliation/run \
  -H 'Content-Type: application/json' \
  -d '{"provider":"openrouter-key"}'

Returned records include provider-reported spend, local estimated spend, delta, drift percentage, missing keys, and unsupported states. Raw keys are never returned.

Billing Import

Open Usage Credits and use Billing import.

The import flow accepts pasted CSV or JSON invoice exports. Recognized columns include:

• date, usage_date, invoice_date, period_start
• provider, vendor, service
• model, model_name, sku
• units, tokens, total_tokens, quantity
• cost, amount, total, total_cost, spend
• currency, invoice_id, line_id, transaction_id, description

Preview first:

curl -X POST http://localhost:4173/api/usage/import/preview \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","sourceName":"July invoice","text":"date,provider,model,units,cost,currency,invoice_id,line_id\n2026-07-01,anthropic,claude-3-5-sonnet,1200,0.42,usd,inv_1,line_1"}'

Import valid non-duplicate rows:

curl -X POST http://localhost:4173/api/usage/import \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","sourceName":"July invoice","text":"date,provider,model,units,cost,currency,invoice_id,line_id\n2026-07-01,anthropic,claude-3-5-sonnet,1200,0.42,usd,inv_1,line_1"}'

The importer rejects token-like secrets, local home paths, unsupported currencies, missing units/cost, and duplicates. It stores normalized ledger records only, not the raw invoice text.

Scheduler

Open Scheduler.

The scheduler can:

• run workflows every X minutes
• create scheduled local module tasks for SEO, Video, Notebook, Kanban, Goals, and Usage Credits
• run scheduled goal_loop actions for Goals and seo_audit actions for SEO
• hold scheduled runs for admin approval before execution
• create Kanban approval cards for approval-gated scheduled runs
• pause and resume jobs
• approve or reject approval-gated jobs
• run a job immediately
• retry non-completed jobs after a retry delay
• keep per-job history
• hold a short-lived leader lock so only one Node process runs due jobs on VPS/Docker

Environment:

HERMES_AGENT_OS_SCHEDULER=1
HERMES_AGENT_OS_SCHEDULER_POLL_MS=30000
HERMES_AGENT_OS_SCHEDULER_LOCK=1
HERMES_AGENT_OS_SCHEDULER_LOCK_TTL_MS=120000

The lock file is reported publicly as ~/.hermes-agent-os/runs/scheduler/scheduler.lock.json; the API never returns the real home directory. If a process dies while holding the lock, another process can take over after the TTL.

API checks:

curl http://localhost:4173/api/scheduler
curl -X POST http://localhost:4173/api/scheduler/tick
curl -X POST http://localhost:4173/api/scheduler/jobs/<job-id>/approve -H 'Content-Type: application/json' -d '{"note":"approved"}'
curl -X POST http://localhost:4173/api/scheduler/jobs/<job-id>/reject -H 'Content-Type: application/json' -d '{"note":"needs review"}'

Goals Loop

Open Goals.

The Goals module can:

• create local goal records
• run a provider-router-backed planning loop for one goal
• keep plan, next action, loop count, and run history on the goal
• record dry-run/executed usage as goal_loop
• stay dry-run unless trusted execution is explicitly enabled
• return redacted API state without raw home paths or key-looking fields

Create a goal in the dashboard, then run a loop from the goal card. API example:

curl -X POST http://localhost:4173/api/self/goals/<goal-id>/loop \
  -H 'Content-Type: application/json' \
  -d '{"provider":"openrouter","context":"Plan the next safe step"}'

Execution requires both:

HERMES_AGENT_OS_ENABLE_EXEC=1

and request body:

{ "dryRun": false }

SEO Audit

Open SEO.

The SEO module can:

• create local SEO briefs with URL, keyword, status, and notes
• plan a Firecrawl scrape in dry-run mode
• plan Firecrawl search-result competitor discovery in dry-run mode
• plan Firecrawl search-result rank snapshots in dry-run mode
• execute the Firecrawl scrape only when FIRECRAWL_API_KEY, HERMES_AGENT_OS_ENABLE_EXEC=1, and "dryRun":false are present
• execute Firecrawl search only when FIRECRAWL_API_KEY, HERMES_AGENT_OS_ENABLE_EXEC=1, and "dryRun":false are present
• route page evidence through Provider Router for score/recommendations
• record usage as seo_audit, seo_competitor_discovery, and seo_rank_snapshot
• store scrape/search status, audit count, competitors, rank snapshots, recommendations, and run history on the brief
• redact Firecrawl keys, provider keys, and local paths

API example:

curl -X POST http://localhost:4173/api/self/seo/<brief-id>/audit \
  -H 'Content-Type: application/json' \
  -d '{"provider":"openrouter","context":"Audit the homepage for conversion-focused SEO"}'
curl -X POST http://localhost:4173/api/self/seo/<brief-id>/discover \
  -H 'Content-Type: application/json' \
  -d '{"limit":10}'
curl -X POST http://localhost:4173/api/self/seo/<brief-id>/rank \
  -H 'Content-Type: application/json' \
  -d '{"limit":20}'

Optional private gateway/test override:

HERMES_FIRECRAWL_SCRAPE_URL=https://api.firecrawl.dev/v2/scrape
HERMES_FIRECRAWL_SEARCH_URL=https://api.firecrawl.dev/v2/search

Video Worker

Open Video.

The Video module can:

• create local video job records with a source file and workflow notes
• inspect media through ffprobe
• prepare dry-run plans for transcription and rendering
• queue long-running video jobs and poll run status
• parse and persist progress samples from STT provider output and ffmpeg time= output
• run Groq/OpenAI/local Whisper STT to produce SRT captions when trusted execution is explicitly enabled
• run ffmpeg copy/remux renders or STT plus ffmpeg caption burn-in when trusted execution is explicitly enabled
• cancel queued/running jobs
• download manifest/SRT/MP4 outputs through safe API routes
• write an execution-gated handoff manifest with command results and output paths
• store probe metadata, duration, dimensions, audio/video state, outputs, command status, command progress samples, and worker run history
• return {{SOURCE_VIDEO}}/filename instead of raw local source paths

Optional command overrides:

HERMES_FFPROBE_PATH=/opt/homebrew/bin/ffprobe
HERMES_FFMPEG_PATH=/opt/homebrew/bin/ffmpeg
HERMES_WHISPER_PATH=/opt/homebrew/bin/whisper
HERMES_VIDEO_STT_PROVIDER=auto
HERMES_VIDEO_GROQ_STT_MODEL=whisper-large-v3-turbo
HERMES_VIDEO_OPENAI_STT_MODEL=whisper-1
HERMES_VIDEO_STT_TIMEOUT_MS=600000
HERMES_VIDEO_CLOUD_STT_MAX_MB=100
HERMES_VIDEO_WHISPER_TIMEOUT_MS=600000
HERMES_VIDEO_FFMPEG_TIMEOUT_MS=600000

Cloud STT is optional and uses user-owned keys. In auto mode Hermes tries GROQ_API_KEY, then OPENAI_API_KEY, then local Whisper. Endpoint overrides HERMES_GROQ_STT_URL and HERMES_OPENAI_STT_URL are available for private gateways and tests.

API checks:

curl http://localhost:4173/api/self/video/worker
curl -X POST http://localhost:4173/api/self/video/<job-id>/run \
  -H 'Content-Type: application/json' \
  -d '{"dryRun":true,"operation":"caption_render"}'
curl -X POST http://localhost:4173/api/self/video/<job-id>/queue \
  -H 'Content-Type: application/json' \
  -d '{"dryRun":false,"operation":"caption_render"}'
curl http://localhost:4173/api/self/video/runs/<run-id>
curl -X POST http://localhost:4173/api/self/video/runs/<run-id>/cancel
curl -OJ http://localhost:4173/api/self/video/runs/<run-id>/download/<file-name>

Supported operations:

• handoff: write a local manifest only
• transcribe: run Groq/OpenAI/local Whisper STT and produce SRT
• render: run ffmpeg remux/copy render
• caption_render: run Groq/OpenAI/local Whisper STT, then burn captions with ffmpeg

Running cloud STT, Whisper, or ffmpeg requires:

HERMES_AGENT_OS_ENABLE_EXEC=1

and request body:

{ "dryRun": false }

Dry-run remains the default. Executed responses include command/provider status, redacted stdout/stderr, selected STT provider/model, progress, progressDetails.samples, captions, renderedVideo, and manifest aliases under ~/.hermes-agent-os/runs/video/<runId>/. Download routes only serve files named in that run's public output aliases.

Memory

Open Memory.

The memory layer can:

• store semantic facts, episodic events, and procedural playbooks
• scope memories per agent and namespace
• search memories with metadata filters
• search with lexical, vector, or hybrid ranking
• build a local hash vector index with no API keys
• use configured Ollama or OpenAI embeddings when the user connects those provider cards
• sync and search an optional Qdrant remote vector collection
• mark memories private, shared, or exportable
• archive/restore memories
• import memory JSON
• export redacted non-private memory by default

API checks:

curl http://localhost:4173/api/memory
curl -G http://localhost:4173/api/memory/search \
  --data-urlencode 'query=setup' \
  --data-urlencode 'type=procedural' \
  --data-urlencode 'mode=hybrid'
curl -X POST http://localhost:4173/api/memory/vector/config \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true,"provider":"local-hash","model":"local-hash-v1","dimensions":96}'
curl -X POST http://localhost:4173/api/memory/vector/rebuild \
  -H 'Content-Type: application/json' \
  -d '{"force":true}'
curl -X POST http://localhost:4173/api/memory/export \
  -H 'Content-Type: application/json' \
  -d '{"includePrivate":false,"includeArchived":false}'

Provider-backed vectors are optional. provider:"ollama" requires OLLAMA_HOST; provider:"openai" requires OPENAI_API_KEY. Missing dependencies return ready_to_configure rather than silently falling back.

Qdrant remote vector memory is optional and keeps the local-first default intact. Use provider:"qdrant" when you want Hermes to sync vector points to a Qdrant collection. The Qdrant API key is write-only in the dashboard/API response; public state only returns hasApiKey.

curl -X POST http://localhost:4173/api/memory/vector/config \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true,"provider":"qdrant","embeddingProvider":"local-hash","model":"local-hash-v1","dimensions":96,"endpoint":"http://localhost:6333","collection":"hermes_memory","apiKey":"optional-qdrant-key"}'
curl -X POST http://localhost:4173/api/memory/vector/rebuild \
  -H 'Content-Type: application/json' \
  -d '{"force":true}'
curl -G http://localhost:4173/api/memory/search \
  --data-urlencode 'query=setup memory' \
  --data-urlencode 'mode=vector'

For Qdrant plus provider embeddings, set embeddingProvider to ollama or openai and make sure the matching provider card is configured first. Missing OLLAMA_HOST or OPENAI_API_KEY returns ready_to_configure.

Skill Registry

Open Skills.

The skill registry can:

• list export-safe sample skills
• import signed external skill bundles
• add remote signed marketplace feeds
• fetch signed marketplace skills without installing them automatically
• trust or untrust publisher fingerprints
• save publisher reputation score, tier, website, and review notes
• enforce optional publisher allowlists and blocklists before marketplace import
• enforce signed skill dependencies before install or enable
• show signed update channels and apply trusted marketplace updates
• verify Ed25519 signatures before accepting a bundle
• reject tampered manifests and publisher fingerprint mismatches
• install a skill locally
• configure required user-owned keys or local endpoints
• enable and disable installed skills
• uninstall skills and remove external bundles
• test skill readiness without exposing secrets
• prepare dependency install suggestions without executing arbitrary code
• show curated release notes from signed manifests and marketplace updates
• keep logs per skill

API checks:

curl http://localhost:4173/api/skills
curl http://localhost:4173/api/skills/marketplace
curl http://localhost:4173/api/skills/publishers
curl -X POST http://localhost:4173/api/skills/memory-curator/install
curl -X POST http://localhost:4173/api/skills/memory-curator/dependencies/prepare
curl -X POST http://localhost:4173/api/skills/memory-curator/test
curl http://localhost:4173/api/skills/memory-curator/logs

Signed bundle shape:

{
  "kind": "hermes.skill.bundle",
  "schemaVersion": 1,
  "manifest": {
    "id": "external-lead-router",
    "label": "External Lead Router",
    "version": "1.0.0",
    "category": "lead",
    "description": "Route inbound leads through configured Hermes providers.",
    "requiredKeys": ["OPENROUTER_API_KEY"],
    "requiredAnyKeys": [["FIRECRAWL_API_KEY", "OLLAMA_HOST"]],
    "optionalKeys": ["HERMES_OPENROUTER_MODEL"],
    "dependencies": [
      {
        "id": "local-ollama-coder",
        "version": "0.1.0",
        "reason": "Reuses local code-planning tools."
      }
    ],
    "updateChannel": "stable",
    "releaseNotes": [
      {
        "version": "1.0.0",
        "title": "Initial release",
        "items": ["Adds a signed lead-routing skill with dependency metadata."]
      }
    ],
    "capabilities": ["lead-routing", "qualification"],
    "permissions": ["model", "workflow", "memory", "network"],
    "samplePrompt": "Qualify this lead and choose the next workflow.",
    "exportSafe": true
  },
  "signature": {
    "algorithm": "ed25519",
    "publicKey": "-----BEGIN PUBLIC KEY-----...",
    "value": "base64-signature"
  }
}

The signature is verified over the canonical manifest JSON. Imported skills are data-only manifests; Hermes does not execute arbitrary code from bundles.

Remote marketplace feed shape:

{
  "kind": "hermes.skill.feed",
  "schemaVersion": 1,
  "skills": [
    {
      "bundle": {
        "kind": "hermes.skill.bundle",
        "schemaVersion": 1,
        "manifest": {
          "id": "external-seo-scout",
          "label": "External SEO Scout",
          "version": "1.0.0",
          "category": "seo",
          "description": "Research pages through configured crawl and model providers.",
          "dependencies": [],
          "updateChannel": "stable",
          "releaseNotes": [
            {
              "version": "1.0.0",
              "title": "Initial marketplace release",
              "items": ["Publishes an export-safe SEO scout skill."]
            }
          ],
          "capabilities": ["seo", "crawl"],
          "permissions": ["model", "network"],
          "exportSafe": true
        },
        "signature": {
          "algorithm": "ed25519",
          "publicKey": "-----BEGIN PUBLIC KEY-----...",
          "value": "base64-signature"
        }
      }
    }
  ]
}

Marketplace flow:

curl -X POST http://localhost:4173/api/skills/marketplace/feeds \
  -H 'content-type: application/json' \
  -d '{"id":"community","label":"Community Skills","url":"https://example.com/hermes-skills.json"}'

curl -X POST http://localhost:4173/api/skills/marketplace/feeds/community/fetch
curl -X POST http://localhost:4173/api/skills/trust/PUBLISHER_SHA256_FINGERPRINT
curl -X POST http://localhost:4173/api/skills/publishers/PUBLISHER_SHA256_FINGERPRINT/reputation \
  -H 'content-type: application/json' \
  -d '{"label":"Reviewed Publisher","score":90,"tier":"verified","website":"https://publisher.example","notes":"Reviewed signed feed."}'
curl -X POST http://localhost:4173/api/skills/publishers/PUBLISHER_SHA256_FINGERPRINT/allow \
  -H 'content-type: application/json' \
  -d '{"label":"Reviewed Publisher"}'
curl -X POST http://localhost:4173/api/skills/publishers/policy \
  -H 'content-type: application/json' \
  -d '{"enforceAllowlist":true}'
curl -X POST http://localhost:4173/api/skills/marketplace/feeds/community/import/external-seo-scout
curl -X POST http://localhost:4173/api/skills/external-seo-scout/update

Hermes redacts feed query strings in public responses. Marketplace skills stay outside the local catalog until their Ed25519 bundle verifies, the publisher is trusted, and the current publisher allow/block policy permits import. If allowlist enforcement is enabled, a trusted publisher must also be allowlisted. A blocked publisher cannot be imported even if it is trusted and allowlisted.

Dependencies and update channels are part of the signed manifest. By default, Hermes refuses to install or enable a skill when a required dependency is missing, disabled, or below the requested minimum version. Marketplace updates use the same publisher trust and allow/block policy checks as first-time imports.

Workflow Execution

The workflow API can execute Open Agent Builder-compatible nodes through Hermes OS:

• graph edges drive execution when present
• old no-edge workflows get implicit node-order edges
• if/else nodes can route through branch labels, source handles, or explicit branch maps
• non-routing nodes with several outgoing edges fan out into parallel branches
• run records include branch IDs, parallel group IDs, and parallel_group_started / parallel_group_completed replay events
• replay records map every workflow node and edge to run status, branch IDs, parallel group IDs, timing, and layout positions
• the upstream builder proxy can load a Hermes replay overlay for a specific workflow run
• while-loop nodes respect iteration limits and the max-step guard
• agent nodes can call the Provider Router or configured CLI modules
• MCP/tool nodes can route through registered OS modules
• Kanban MCP/tool nodes create source-linked local task cards
• failed nodes can retry when maxRetries is set
• user approval nodes pause a run until the resume endpoint is called and create Kanban approval cards
• run records include node attempts, traversed edges, status, timing, output summary, logs, and replayable events

API checks:

curl -X POST http://localhost:4173/api/workflows/blank-open-agent-builder/run \
  -H 'Content-Type: application/json' \
  -d '{"trigger":"setup-check"}'

curl http://localhost:4173/api/workflows

Event replay endpoint:

curl http://localhost:4173/api/workflows/<workflow-id>/runs/<run-id>/events
curl -H 'Accept: text/event-stream' http://localhost:4173/api/workflows/<workflow-id>/runs/<run-id>/events
curl http://localhost:4173/api/workflows/<workflow-id>/runs/<run-id>/replay
curl 'http://localhost:4173/api/builder/replay-overlay?workflowId=<workflow-id>&runId=<run-id>'

Open the real upstream builder with the Hermes replay overlay attached:

http://localhost:4173/agent-builder-source/?view=builder&hermesReplay=1&hermesWorkflowId=<workflow-id>&hermesRunId=<run-id>

Approval resume endpoint:

curl -X POST http://localhost:4173/api/workflows/<workflow-id>/runs/<run-id>/resume \
  -H 'Content-Type: application/json' \
  -d '{"approved":true}'

Ollama

Install Ollama, then run a model:

ollama pull llama3.1
ollama serve
curl http://127.0.0.1:11434/api/tags

Set:

OLLAMA_HOST=http://127.0.0.1:11434
HERMES_OLLAMA_MODEL=llama3.1

Then configure provider-ollama in the dashboard or through /api/connections/provider-ollama/configure.

Inventory check:

curl http://localhost:4173/api/setup/providers/ollama/models

Expected states:

• ready_to_configure when OLLAMA_HOST is missing
• error when the host is configured but Ollama is not reachable
• connected with real model names, sizes, parameter size, quantization, and total local model size when /api/tags responds

OpenRouter And MiniMax

Set one or both:

OPENROUTER_API_KEY=
OPENROUTER_MANAGEMENT_KEY=
MINIMAX_API_KEY=
OPENAI_ADMIN_KEY=
HERMES_OPENROUTER_MODEL=openrouter/auto
HERMES_MINIMAX_MODEL=MiniMax-M3

Configure these through the provider cards or /api/connections/:id/configure. The backend redacts stored secret values from public responses and logs.

Firecrawl Open Agent Builder

The real upstream builder source is in:

vendor/open-agent-builder/

Install and start it:

npm run builder:install
npm run builder:start

Required before execution:

NEXT_PUBLIC_CONVEX_URL=
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
CLERK_JWT_ISSUER_DOMAIN=
FIRECRAWL_API_KEY=

Check:

curl http://localhost:4173/api/builder/status
curl http://localhost:4173/api/builder/bootstrap
curl 'http://localhost:4173/api/builder/replay-overlay?workflowId=blank-open-agent-builder&runId=<run-id>'
curl http://localhost:4173/api/builder/logs

Supervisor controls:

curl -X POST http://localhost:4173/api/builder/bootstrap/prepare
curl -X POST http://localhost:4173/api/builder/smoke-test
curl -X POST http://localhost:4173/api/builder/start
curl -X POST http://localhost:4173/api/builder/stop

The bootstrap endpoint returns a dry-run command checklist for the upstream source, dependency install, Convex project, Clerk app, Firecrawl key, LLM key, supervisor start, and smoke test. The smoke test reports setup_required, ready_to_start, or live without exposing stored key values. The supervisor refuses to start until the upstream source, dependencies, Convex, and Clerk are ready. It reads config from the Firecrawl Builder card and the provider cards, then stores only sanitized boot logs. The replay overlay endpoint never returns secrets, local paths, raw env values, or private workflow history beyond the requested sanitized workflow/run replay.

Docker

cp .env.example .env
docker compose up --build

Open:

http://localhost:4173

Runtime data is stored in the hermes-agent-os-data volume at /data/hermes-agent-os.

Run the smoke test before shipping a zip, pushing a release, or deploying to a VPS:

npm run smoke:docker

What it proves:

• the Docker image builds from the clean repo context
• the container boots with HERMES_AGENT_OS_ENABLE_EXEC=0 and HERMES_AGENT_OS_ENABLE_INSTALL=0
• runtime state uses a temporary /data/hermes-agent-os Docker volume
• /api/health, /api/os/kernel, and /api/modules respond from inside the container
• Docker healthcheck reaches healthy
• host home paths are not leaked in the smoke responses
• the temporary container and volume are cleaned up afterward

CI mode:

HERMES_DOCKER_SMOKE_REQUIRED=1 npm run smoke:docker

If Docker is unavailable, normal local mode reports a JSON skip. Required mode fails so CI does not silently pass without Docker.

Public VPS Safety

For a public tunnel or VPS, set:

HERMES_AGENT_OS_PUBLIC_MODE=1
HERMES_AGENT_OS_REQUIRE_AUTH=1
HERMES_AGENT_OS_ADMIN_TOKEN=your-admin-token
HERMES_AGENT_OS_COOKIE_SECURE=1
HERMES_AGENT_HUB_PUBLIC_URL=https://your-domain.example

Protected in public mode:

• setup writes
• guided provider setup writes/tests/model helpers
• connection configuration
• module test/run/logs
• installers
• scheduler jobs, ticks, history, pause/resume
• memory create/search/import/export
• skill install/configure/enable/disable/test/logs
• usage budgets, manual usage records, billing import, and billing reconciliation
• workflows
• self-module data
• provider router run/configure
• export prepare

Clean Export

npm run prepare-export

The export audit rejects secrets, local home paths, .data, logs, runtime state, Hermes profile paths, local profile names, and private workflow data.

Verification Checklist

npm test
npm run build
curl http://localhost:4173/api/health
curl http://localhost:4173/api/os/kernel
curl http://localhost:4173/api/os/audit
curl http://localhost:4173/api/setup/providers
curl http://localhost:4173/api/router
curl http://localhost:4173/api/router/status
curl http://localhost:4173/api/router/health
curl http://localhost:4173/api/usage
curl http://localhost:4173/api/usage/reconciliation
curl http://localhost:4173/api/scheduler
curl http://localhost:4173/api/memory
curl http://localhost:4173/api/skills
curl http://localhost:4173/api/skills/marketplace
curl http://localhost:4173/api/skills/publishers
curl http://localhost:4173/api/self/video/worker
curl -X POST http://localhost:4173/api/self/video/<job-id>/queue \
  -H 'Content-Type: application/json' \
  -d '{"dryRun":true,"operation":"caption_render"}'
curl http://localhost:4173/api/workflows
curl http://localhost:4173/api/builder/status
curl 'http://localhost:4173/api/builder/replay-overlay?workflowId=blank-open-agent-builder&runId=<run-id>'
curl http://localhost:4173/api/builder/logs

Expected:

• tests pass
• build passes
• /api/health returns ok: true
• /api/os/kernel returns runtime core, module registry, scheduler, memory, skill registry, provider router, workflow engine, usage ledger, builder adapter, and safety components without local home paths or secrets
• /api/setup/providers returns provider-specific guides, configured field names, missing field names, and helper metadata without raw secrets
• /api/setup/providers/ollama/models returns real local Ollama model inventory or an honest setup/error state
• /api/router and /api/router/status return the same provider router state
• /api/router/health returns setup states until provider keys/endpoints are configured, then safe health probe results
• /api/modules/:id/run stays dry-run unless HERMES_AGENT_OS_ENABLE_EXEC=1 and dryRun:false are both present; CLI adapter outputs are structured and redacted
• /api/self/goals/:goalId/loop runs a dry-run-first Provider Router goal loop, scheduler goal_loop jobs can hold for approval before execution, stores next action/history, records goal_loop usage, and does not return raw home paths or keys
• /api/self/seo/:briefId/audit runs a dry-run-first Firecrawl plus Provider Router SEO audit, scheduler seo_audit jobs can run recurring audits, stores recommendations/history, records seo_audit usage, and does not return raw home paths or keys
• /api/self/seo/:briefId/discover and /api/self/seo/:briefId/rank run dry-run-first Firecrawl search-result competitor discovery and target-domain rank snapshots, store competitors/rank history, record usage, and do not return raw home paths or keys
• /api/self/video/worker reports ffprobe/ffmpeg/Whisper and Groq/OpenAI STT readiness, /api/self/video/:jobId/run runs immediate jobs, /api/self/video/:jobId/queue queues jobs, /api/self/video/runs/:runId polls status/progress with command-derived progressDetails.samples, cancel/download routes work, and public responses do not return raw source paths
• /api/usage returns budget state, spend summary, ledger entries, and reconciliation summary
• /api/usage/reconciliation returns supported, missing-config, and unsupported provider billing states without raw keys
• /api/scheduler returns scheduler summary, jobs, and target lists
• /api/memory returns memory summary, vector state, and optional Qdrant remote metadata without Qdrant API keys
• /api/skills returns sample skills, signed external bundle counts, signed dependency status, marketplace update counts, publisher trust/allow/block counts, and install/test state
• /api/skills includes dependency install suggestions and curated release notes without raw secrets
• /api/skills/marketplace returns saved feeds, fetched signed skills, trusted publishers, publisher reputation, signed dependency metadata, dependency suggestions, update channel state, curated release notes, allow/block policy state, and no raw feed secrets
• /api/skills/:id/dependencies/prepare returns a dry-run dependency action plan with install/import/update commands
• /api/skills/publishers returns known publishers, trust state, reputation, allowlist state, blocklist state, and import eligibility
• workflow runs return node attempt timelines, traversed edges, event replay, visual replay graph data, branch/parallel/loop routing, Kanban task cards, and pause on human approval nodes with Kanban approval cards
• /api/builder/replay-overlay returns sanitized overlay mode, selectors, run summary, node badges, and traversed-edge lines for the real upstream builder proxy
• /api/builder/status returns upstream source, dependency, supervisor, and config diagnostics
• /api/builder/bootstrap returns dry-run setup steps and command contracts for Convex, Clerk, Firecrawl, LLM keys, supervisor start, and smoke test
• /api/builder/smoke-test returns credential readiness checks without raw secrets or local home paths
• /api/builder/logs returns sanitized start/stop/boot logs
• provider cards say ready_to_configure until keys/endpoints are configured
• CLI cards only say connected when the CLI/path exists
• OpenClaude remains missing unless a real local compatible CLI path is configured
• export audit passes before distribution
• npm run smoke:docker passes when Docker is available, or reports a JSON skip when Docker is unavailable and HERMES_DOCKER_SMOKE_REQUIRED is not set