Runtime Assembly and Deployment

Protocol version 2 uses an authenticated outbound Server-Sent Events control stream to notify the runtime adapter of durable work. The adapter claims an inbound Delivery, invokes the selected runtime, submits the reply against the source Delivery, and completes the Delivery.

PostgreSQL owns delivery state, claims, leases, idempotency, and cancellation. Redis Streams provide content-free wakeups rather than authoritative message state. Reconnect replay and bounded fallback wakeups recover durable work when a signal is missed or Redis is unavailable. The adapter retains a five-second safety claim poll.

Claims last 120 seconds. Hermes renews its live claim every 60 seconds while its asynchronous run or approval is active. OpenClaw retains the bounded-turn behavior of its chat-completions path. Do not infer that both runtimes have the same progress, approval, or abort transport merely because they share Communications.

POST .../deliveries/{delivery_id}/renew?awaiting_input=true renews the live claim while reporting that its run is parked for a human answer. The flag defaults to false and is reported again on lease heartbeats. A waiting claim does not block the next inbound answer on the same ordering key. A newly claimed Delivery starts with the flag false. This is processing state on a claim, not a new terminal Delivery status, an authorization bypass, or a revival of an expired claim.

Version-1 claim/reply/complete routes remain accepted while older Agents are rebuilt. Updating a Connection reconciles provider connectivity separately from restarting the runtime.

Communications → shared adapter → Hermes /v1/runs; shared adapter → OpenClaw /v1/chat/completions. The SSE control stream carries work notifications, not token-by-token model responses.

Communication Connection credentials are not decrypted into the Runtime, and provider tokens for Slack, Microsoft Teams, Telegram, or Discord are never materialized into Hermes or OpenClaw.

A Runtime startup or Kubernetes failure can move an Agent to ERROR. A provider-session or Connection failure changes Connection health instead of Agent lifecycle.

Agent Barn starts the Hermes boot runner alongside the gateway. When BOOT.md is non-empty, the runner waits for the local API to accept a /v1/runs submission. The run uses a reserved no-conversation session with session resume disabled and is intended for repeatable startup work. The runner can wait up to 300 seconds for readiness.

The startup log confirms that the boot run was submitted. The runner does not wait for the checklist to finish, so that log is not proof that setup succeeded. Inspect the gateway log for the outcome. A comments-only but non-empty BOOT.md is still non-empty and is submitted.

Loads the Organization-owned Agent and its pinned Template or Agent Template Override Version.

Resolves and renders the Agent's current configuration.

Decrypts Agent Secrets used by tool Integrations.

Selects the Hermes or OpenClaw Runtime builder.

Combines explicitly assigned Skill Versions with eligible built-in provider Skills.

Materializes supported Integration configuration.

Appends tool pointers and unconditional runtime behavior policies.

Generates fresh Ingest and Communications protocol credentials.

Builds the ConfigMap, Secret, PVC, Service, and Deployment resources, including the runtime-neutral Communications adapter.

Applies the Kubernetes resources and transitions the Agent to running when startup succeeds.

Platform selection is not part of Agent creation. An Agent may be headless or own zero or many Communication Connections, including multiple Connections to the same Platform; see /guides/agents/communication-connections for Connection lifecycle. Adding a Platform should add one Platform Plugin and provider adapter rather than changes to both Runtime builders.

Each shipped Platform Plugin owns:

Typed Connection settings

Typed credential schemas

External credential validation

Credential identity and uniqueness rules

Provider ingress or supervised sessions

Message normalization and admission policy

Optional directory and name enrichment

Outbound provider delivery

Optional processing feedback

Provider health observation

Slack ingress: supervised Socket Mode

Telegram ingress: supervised polling

Discord ingress: supervised Gateway session

Microsoft Teams ingress: authenticated provider webhook

The Runtime uses Connection-scoped session identity but does not receive provider credentials. Durable delivery, leases, ordering, idempotency, and provider retries belong to Communications, not to the Runtime.

Communication Connection settings and credentials have an independent lifecycle: updating a Connection increments its revision, and the Communications Gateway reconciles the provider session without restarting a running Agent. Connection health and Agent lifecycle remain separate, and one failed Connection does not stop another Connection or automatically move the Agent to ERROR.

Inbound: Communication Platform

Inbound: Platform Plugin

Inbound: Communications Gateway

Inbound: Durable Communication Delivery

Inbound: Runtime-neutral adapter

Inbound: Hermes or OpenClaw

Outbound: Hermes or OpenClaw

Outbound: Runtime-neutral adapter

Outbound: Durable Communication Delivery

Outbound: Communications Gateway

Outbound: Platform Plugin

Outbound: Communication Platform

Hermes scheduled jobs created from a conversation retain its Connection, channel, and thread. Startup-created jobs use the default. OpenClaw uses the default only when a completion has no recorded origin. Its pinned cron hook can expose a delivery-channel label instead of the creating conversation; an unmappable origin is refused instead of being sent to the default.

Hermes captures scheduled final responses at a scheduler completion boundary in its image and suppresses native provider delivery. OpenClaw captures completions through its in-process agent_end hook. Both write eligible completions to a runtime-local SQLite spool before returning from the hook. A separate drain process submits them to Communications with a stable run identity.

Communications resolves the destination and atomically persists a canonical outbound message and durable Delivery before acknowledging acceptance. The resolved destination is retained for retries. The Platform Plugin checks the Connection's current outbound policy again before provider delivery. Acceptance is not provider success.

For a job created in a channel thread, an explicit delivery setting may change the thread within that same channel. To post at the channel root, use <platform>:<channel-id>: with the final thread segment empty. To target a particular thread, include its ID in that segment. Naming a different channel is refused; it does not redirect the result. This syntax belongs to the scheduled job's delivery configuration, not its prompt or the default-target form.

The local spool retries a scheduled submission under the same run identity until it is acknowledged, receives a permanent client-error refusal, or exhausts its bounded retry budget, approximately one day of transient failures. The implementation uses an attempt limit, not an exact 24-hour expiration. Settled rows are retained for seven days before pruning. Accepted work then follows the server's durable Delivery lifecycle; local submission retries and server provider-delivery retries are different stages.

An unmappable origin is refused before a deliverable completion is captured. A permanent refusal must be diagnosed; it is not automatically replayed when configuration later changes. Changing a default or enabling a Connection does not recover every previously refused completion.

Return a recognized silence marker when there is nothing worth sending: [SILENT], SILENT, NO_REPLY, NO REPLY, or HEARTBEAT_OK. Matching is case-insensitive and ignores surrounding whitespace. An empty response is also suppressed.

The current filter checks the whole response and its first and last non-empty lines. A standalone marker on either of those lines suppresses the entire result, even if other lines contain a substantive report. Do not append a silence marker to a report you want delivered. Text such as Nothing to flag today. is not a silence marker and remains eligible for delivery.

Eligible describes the silence filter only; routing, admission, and provider delivery can still refuse or fail.

NO_REPLY: suppressed.

A report followed by a final standalone NO_REPLY line: entire response suppressed.

A first standalone NO_REPLY line followed by a report: entire response suppressed.

Nothing to flag today.: eligible for delivery.

Report [SILENT] on one line: eligible for delivery.

The Communications Gateway persists canonical inbound and outbound Conversation Messages; the Ingest API persists authenticated Runtime Tool Call telemetry. These are separate write paths, not a single stream from the Runtime through Ingest.

The Product API provides authorized reads for the Activity interface. Ingest is not the source of canonical Conversation Messages.

Each conversation location belongs to a particular Communication Connection, and its identity includes both the Connection ID and the provider channel ID. Two Connections can use the same provider channel identifier without combining their histories.

Tool Call identity is scoped by Agent and Runtime invocation identity.

Costs read stored cost records synchronized from LiteLLM spend logs with OpenRouter missing-charge recovery; they are not calculated from Conversations or Tool Calls.

See /guides/activity-conversations-and-telemetry for the complete Conversation, Tool Call, and cost-attribution model.

Incoming chat message: the provider sends it to Communications, which records the accepted message and prepares it for the Agent.

Agent reply: the Runtime submits a reply through Communications, bound to the originating Communication Delivery and its Connection; Communications records the reply and sends it to the provider.

Tool Call or tool result: the Runtime sends telemetry to Ingest, which records the Tool Call and updates its result.

These diagnostic writes are best-effort. If one fails, Agent Barn logs the failure and continues handling otherwise valid provider traffic. A diagnostic storage problem should not cause an already-consumed provider message to be lost.

This behavior applies to observation and policy-admission journal entries. It does not make message storage or durable Communication Delivery records optional, and it does not bypass a policy decision that rejects a message.

See /guides/observe-and-govern/communication-diagnostics for Connection status, delivery history, and recovery actions.

For example, a chat reply can fail because the Runtime could not complete its work, even when the provider Connection is healthy.

Chat messages or replies are missing: start with the affected Connection and its Communications delivery diagnostics.

Conversations work but Tool Calls are missing: start with the Runtime telemetry path to Ingest.

The Agent Runtime does not become ready: start with Runtime health and logs.

Spend information is missing or unexpected: start with stored cost attribution, synchronization freshness, and the selected reporting period.

Product routes are mounted under /api/v1, Runtime Tool Call telemetry under /ingest/v1, and the Runtime Communications protocol and provider ingress under /communications/v1. The Communications service is deployed separately from the Product API process and supervises provider ingress and outbound delivery.

Only the provider-webhook prefix requires public Communications ingress; Runtime protocol traffic remains internal. Communications durable delivery is separate from Domain Event delivery.

Product API on port 8000

Ingest API on port 8001

Communications service on port 8002

Web app, PostgreSQL, Redis, and LiteLLM

Domain Event delivery worker and reconciliation CronJob

Monitoring stack

Hermes and OpenClaw Runtime images

Kubernetes resources for running Agents

Hosted public production runs on the separate Talos cluster and deploys only from a vX.Y.Z Git tag, or a manual dispatch of an existing release tag; public API and UI images are pinned to that release tag in registry.agentbarn.dev. A public deployment and the k3s testing deployments are separate workflows.

See /guides/self-hosting/deploy-kubernetes and /guides/self-hosting/upgrades for the operational deployment and upgrade procedures.

The default namespace-scoped Prometheus configuration collects Product API metrics on port 8000, Ingest metrics on port 8001, LiteLLM metrics, Agent Runtime health, and Kubernetes workload state. Alertmanager routes configured alerts to Slack, and Grafana provides dashboards.

Communications exposes metrics on port 8002, but the default monitoring configuration does not collect them. Add a Prometheus scrape target for the Communications Service to collect these metrics. Keep the endpoint internal; see /guides/self-hosting/communications for the collection boundary and configuration guidance.

Communications exposes low-cardinality metrics for Connection status, delivery outcomes, queue depth, oldest queued delivery age, delivery latency, reconnect requests, and policy dispositions.

See /guides/agents/choose-runtime for Runtime selection guidance and /guides/platforms/compatibility for current Platform behavior.