Architecture

OpenHermit is a gateway-managed, multi-agent runtime. The gateway owns process lifecycle, the API surface, the channel-bridge pool, and the central cron scheduler. Per agent, an in-process AgentRunner carries the workspace, security policy, tools, MCP connections, and per-session state — runners hydrate on demand when traffic arrives and are LRU-evicted when idle (controlled by OPENHERMIT_EVICTION_TTL_MINUTES, default 30). agents.status ('active' / 'disabled') in the DB is the source of truth for whether traffic is accepted; the in-memory runner map is a hydration cache, not a lifecycle.

Components

CLI / Web / Channels / API clients
          |
          v
Gateway (Hono HTTP + WebSocket, auth, admin UI)
          |
          v
AgentInstanceManager
          |
          +-- AgentRunner(agent A) -> exec backend -> docker / host / e2b / daytona
          +-- AgentRunner(agent B) -> exec backend -> docker / host / e2b / daytona
          |
          v
PostgreSQL stores (Drizzle)

Component	Responsibility
apps/gateway	Control plane, auth, admin API, admin UI, agent lifecycle, WebSocket attachment, channel startup
apps/agent	Agent loop, prompt assembly, tools, sessions, events, introspection, compaction, MCP client manager
apps/cli	Setup, gateway lifecycle, agent management, chat TUI, config/secrets, schedules, logs/status
apps/web	Standalone end-user chat web app
apps/channels/*	Bundled bridges (Telegram, Discord, Slack) plus external plugins (e.g. @openhermit/channel-wechat) — all loaded uniformly through the ChannelManifestRegistry
packages/protocol	Shared contracts and route builders
packages/sdk	HTTP/SSE/WebSocket clients used by CLI/channels
packages/store	Drizzle schema and PostgreSQL store implementations
packages/shared	Errors, env loading, URL helpers, OpenHermit home helpers

State Boundary

OpenHermit keeps internal runtime state separate from external task state.

Internal state is owned by OpenHermit and stored in PostgreSQL unless noted:

• agent records
• sessions and session events
• working memory and session descriptions
• long-term memories
• instructions
• users, roles, identities, and merges
• sandbox rows (per-agent execution environments) and their runtime state
• skills and skill assignments
• MCP server definitions and assignments
• schedules and schedule runs
• per-agent runtime config and security policy (agents.config_json / agents.security_json columns)
• per-agent secrets (encrypted in the agent_secrets table when OPENHERMIT_SECRETS_KEY is set; falls back to per-agent secrets.json only when no key is configured)
• channel rows with encrypted tokens (agent_channels) and encrypted channel-owned auth state (agent_channel_credentials)

External state is the user's work surface:

• workspace files
• generated artifacts
• project repositories
• mounted data under the workspace
• workspace-installed skills under .openhermit/skills

Per-Agent State

Runtime config, security policy, per-agent secrets, and channel-owned credentials are stored in PostgreSQL (agents.config_json, agents.security_json, agent_secrets, agent_channel_credentials) and managed through the admin UI, REST API, or hermit config ... / hermit security .... Channels live in agent_channels with encrypted tokens, managed through /api/agents/{agentId}/channels/.... Secrets and channel credential rows are encrypted at rest with OPENHERMIT_SECRETS_KEY; if no key is configured the gateway falls back to a plaintext secrets.json per agent for local-dev secrets only.

Per-agent state lives in Postgres; the only per-agent artifact on disk is the workspace:

~/.openhermit/
├── gateway/             # gateway.json, .env, registry/, logs
└── workspaces/{agentId}/

Enabled skills are synced into each backend's own sandbox at <agent_home>/.openhermit/skills/system/ rather than living under a gateway-side per-agent dir.

config_json controls model, exec backend, web provider, and memory introspection. security_json controls autonomy level, approval policy, access level, and access token. Secrets are referenced from config values with ${{SECRET_NAME}} and resolved through SecretStore at adapter-start time.

Per-agent instructions (the keyed sections of the system prompt) live in the instructions table, scoped by agent_id like schedules — there is no shared/global row. Each new agent is auto-seeded with three rows on creation: identity, soul, and rules. Owners edit their own; admins can apply the same mutation across every agent with --all (e.g. hermit instructions append rules "Always cite the source URL." --all), backed by POST /api/admin/instructions/fanout with { mode: 'set' | 'append' | 'remove', key, content? }.

Gateway Runtime

On startup, the gateway:

1. loads environment variables
2. loads ~/.openhermit/gateway/gateway.json
3. opens PostgreSQL stores if DATABASE_URL is available
4. scans and registers built-in skills from skills/
5. starts the Hono server and WebSocket handler
6. loads the ChannelManifestRegistry — bundled defaults (Telegram/Slack/Discord) plus any plugin packages named in gateway.config.channelPackages (e.g. @openhermit/channel-wechat) — and boots the channel pool, attaching each adapter's webhook handler to gateway HTTP routes; runners hydrate lazily on first inbound traffic

Agents hydrate on demand: the first request that targets an agent constructs its AgentRunner, syncs enabled skills into the sandbox via runner.syncSkills, attaches existing channel outbounds from the pool, and connects enabled MCP servers lazily through the runner. Schedules fire from a single gateway-level CentralScheduler that hydrates the target runner on demand at fire time. Idle runners are evicted by an LRU after OPENHERMIT_EVICTION_TTL_MINUTES; channel bridges in the pool stay alive across eviction.

Agent Runtime

AgentRunner owns:

• durable session open/resume/list/delete behavior
• user and role resolution
• message queueing per session
• prompt assembly from instructions, memory, skills, user context, and recent history
• tool creation and role-based filtering
• tool approval pauses
• event persistence and realtime publication
• context compaction for long sessions
• introspection for memory and session metadata maintenance
• schedule execution host callbacks
• MCP tool discovery and namespacing
• channel outbound adapters for proactive session_send
• the Deep Research orchestrator (see below)

The main model loop is backed by @mariozechner/pi-agent-core and @mariozechner/pi-ai.

Deep Research

Deep Research is a durable, session-attached workflow — not a tool and not a separate app. A ResearchOrchestrator (owned by AgentRunner, algorithm in apps/agent/src/research/) drives a bounded plan → approve → search/read/ extract → synthesize loop:

• Models run as stateless phase calls (planner, action decider, per-source evidence extractor, synthesizer) with no tools; output is Zod-validated JSON with one repair attempt. The orchestrator — not the model — decides whether proposed actions are allowed and affordable (source policy, hard budgets with a synthesis reserve, duplicate-query and canonical-URL dedupe, concurrency caps, a deterministic finish gate, and a zero-information-gain stop).
• Every external action is a durable, idempotent research_steps row written before execution; sources keep normalized text snapshots and hashes; evidence excerpts are verified verbatim against snapshots before insert. Report claims cite evidence IDs, validated server-side — unsupported findings downgrade to labeled caveats and citations render from durable records, never from model-supplied URLs.
• Retrieved page content is untrusted data: it reaches only the no-tools extractor inside an explicit envelope, and direct page fetches go through the shared SSRF-safe fetch (apps/agent/src/network/safe-fetch.ts).
• Runs pause on graceful shutdown; stale active runs reconcile to paused(runtime_restart) on hydration and resume manually. Chat turns in a session with an actively executing run are rejected with 409 research_run_active.

Authoritative design: deep-research-design.md.

Execution Backends

The exec tool uses ExecBackendManager, built from the agent's rows in the sandboxes table (see sandbox-model.md).

Supported backend types:

• docker: per-agent workspace container managed by the gateway
• host: runs commands on the gateway host (devops-only — see sandbox-model.md)
• e2b: runs commands in a per-agent E2B cloud sandbox
• daytona: runs commands in a per-agent Daytona cloud sandbox

Agents created through the gateway use the preset named by autoProvisionSandbox in gateway.json (default: docker-ubuntu); pass sandbox: "<preset>" or null on POST /api/agents to override.

Sandbox lifecycle (per backend) supports:

• start: ondemand or session
• stop: idle or session
• idle timeout in minutes

Auth

Admin APIs require GATEWAY_ADMIN_TOKEN. Agent routes use a resolver that accepts:

• admin bearer token
• browser/device JWTs issued by POST /api/auth/token (user-global; the JWT identifies a person, not an agent)
• channel bearer tokens registered for built-in or external channel adapters

Agent access can be public, protected, or private. protected requires the agent access token during device-token exchange (members self-join via /members); private rejects anyone without an explicit membership row at session-open time. See sandbox-model.md for the full policy.

Extension Surfaces

• Tools: built-in toolsets plus dynamically connected MCP tools
• Skills: prompt instructions and supporting files, registered in DB and synced into each backend's sandbox via runner.syncSkills
• Channels: Telegram, Discord, Slack as bundled built-ins; additional adapters loaded as npm plugins via channelPackages (e.g. @openhermit/channel-wechat). All registered through the ChannelManifestRegistry. See channel-adapter.md and channel-plugin-design.md.
• Schedules: cron/once jobs that post prompts into dedicated or configured sessions
• Web providers: Defuddle, Exa, Tavily

Development Commands

npm run dev:gateway
npm run dev:web
npm run dev:cli
npm run dev:studio
npm run typecheck
npm test