# Setup and Kubernetes

Configure the plugin, deployers, Kubernetes runtimes, and Postiz installation.


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](https://erxes.io/docs/company-brain-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:

```sh
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](https://erxes.io/docs/company-brain-troubleshooting)
and [How it works](https://erxes.io/docs/company-brain-architecture).