Setup and Kubernetes

This page is for developers and operators enabling the Company Brain plugin on an erxes installation, including the Kubernetes runtimes behind OpenClaw and Hermes and the Postiz installation. End users can skip to Getting started.

What you are deploying

Company Brain is not one container. Expect four cooperating layers:

• agent_api — the plugin backend (GraphQL via the gateway, tRPC, MongoDB).
• agent_ui — the private Module Federation remote consumed by core-ui.
• Assistant runtimes — one isolated runtime per OpenClaw or Hermes assistant.
• The Postiz gateway with its assigned Postiz instance(s).

OpenClaw runtimes

OpenClaw assistants run on a Kubernetes cluster. The deployer chooses the Kubernetes provisioner when USE_K8S_PROVISIONER=true; otherwise it falls back to the legacy per-VM provisioner. Each assistant becomes a Deployment, Service, Secret, and Ingress entry in the cluster, with a pinned OpenClaw image.

Hermes runtimes

Hermes uses a separate in-cluster controller (two replicas) that renders runtime configuration and drives Kubernetes directly. Each Hermes assistant gets its own namespace with a Deployment, Service, Secrets, a ConfigMap, and two persistent volumes (home and workspace). The controller proxies the WebUI and the signed Discord adapter on the same runtime URL, backed by a retain-class storage policy.

Postiz

Postiz is a workspace on a shared, gateway-managed Postiz installation — not a pod per tenant. The gateway reserves one instance per tenant and exposes the workspace through your erxes page.

Prerequisites

• An authorized erxes source checkout (the agent plugin is private).
• The existing platform stack: MongoDB, Redis, the API gateway, and core-api.
• A Kubernetes cluster with cluster credentials, persistent storage (a storage class whose volumes are retained), DNS, and TLS ingress for runtime URLs.
• A secret manager or encrypted deployment-secret workflow — never commit credentials.
• For Postiz: a patched Postiz backend and the gateway with its registry of approved instances.

Enable the plugin locally

From the erxes repository root:

pnpm install
cp .env.sample .env    # add agent to ENABLED_PLUGINS
pnpm nx build agent_api
pnpm nx build agent_ui
pnpm nx serve agent_api
# in a second terminal
pnpm nx serve agent_ui

The UI is consumed by core-ui through Module Federation; run the existing core stack (gateway, core-api, core-ui) as you normally do. The plugin's backend listens on its own port (33010) and registers with the gateway through Redis service discovery.

Environment variables

Names only — provision values through your secret manager.

agent_api

• DEPLOYER_URL — managed deployer base URL.
• MANAGED_OPENCLAW_DEPLOYER_SECRET — deployer authentication header value.
• ERXES_AI_ASSISTANT_RUNTIME_SHARED_SECRET — shared runtime secret; must match what the assistant gateway and runtimes use.
• DOMAIN, MONGO_URL, REDIS_HOST, REDIS_PORT — existing platform settings.
• JWT_TOKEN_SECRET — stable, at least 32 characters; also derives the CMS bridge key for Postiz.

Managed deployer (OpenClaw)

• MANAGED_OPENCLAW_DEPLOYER_SECRET — must match agent_api.
• USE_K8S_PROVISIONER — set true for Kubernetes runtimes.
• OPENCLAW_IMAGE — pinned runtime image.
• Cluster credentials, proxy domain, ingress scheme/TLS secret, and storage settings per your deployer deployment; see the deployer documentation.

Hermes controller

• HERMES_K8S_DEPLOYER_URL and HERMES_K8S_DEPLOYER_SECRET — how the deployer relay reaches the controller.
• The controller requires its deployer secret at startup and fails closed without it; runtime images are pinned per release.

Postiz

Enterprise installations keep one permanent setting on agent_api:

• POSTIZ_GATEWAY_ORIGIN — the Postiz gateway HTTPS origin.

plus the existing DOMAIN (HTTPS origin) and a stable JWT_TOKEN_SECRET (32+ characters). Enterprise enrollment credentials live encrypted in the plugin-owned agent_postiz_installations collection; back it up together with JWT_TOKEN_SECRET and re-encrypt before rotating that secret.

Shared SaaS deployments are configured permanently through deployment secrets instead:

• POSTIZ_MANAGEMENT=saas
• POSTIZ_INSTALLATION_ORIGIN — restricted to the approved managed base origins
• POSTIZ_INSTALLATION_ID
• POSTIZ_GATEWAY_SIGNING_KEY

plus the gateway URL. SaaS mode never reads the encrypted credential store and never falls back to it; missing or partial credentials leave Postiz unconfigured.

Rollout order

1. Deploy infrastructure first: Postiz backend and gateway, the deployer, and the Hermes controller, in whichever order your runbook requires.
2. Deploy agent_api and verify the federated schema exposes the Company Brain operations.
3. Publish agent_ui last — the UI requires the newer API contracts and fails against older APIs.
4. For the CMS → Postiz bridge, coordinate content_api and agent_api in the same window; old and new envelope formats are incompatible.

Smoke checks

• Create an assistant of each kind; confirm provisioning completes and health turns serving.
• Invite a member and confirm they can open the runtime but not manage it.
• Confirm a non-member cannot open the runtime or see a workspace URL.
• Complete a provider connection (API key and subscription flow) and verify chat works; sign in again is not required after a runtime restart.
• For Postiz: owner setup, initial admin selection, member invite, and a non-member denial without any workspace URL exposure.
• Restart a Hermes runtime and confirm state and credentials persist.

Backups and lifecycle

• Back up agent_postiz_installations and JWT_TOKEN_SECRET together for enterprise; back up SaaS deployment secrets alongside the gateway's keys and registry.
• Retained storage means destroyed Hermes runtimes leave volumes behind — include them in your storage cleanup and backup procedures.
• Never roll the gateway below its minimum supported version after enrollment or revocation; older versions ignore the newer credential controls.

Continue to Access and troubleshooting and How it works.