Skip to content
Lobu Lobu
API Blog

Architecture

Lobu is embedded-only: the gateway, agent workers, the embeddings model, and the Lobu memory backend all run inside one Node process (lobu run, or make dev / bun run dev in the monorepo). Workers are not separate services — the gateway spawns each one as a child_process.spawn subprocess on the same host (wrapped in a systemd-run --user --scope on Linux for cgroup limits and capability drops). There is no Docker or Kubernetes deployment manager and no per-conversation container.

Operating loop

One loop behind every AI teammate.

Connect sources, keep shared memory current, and expose safe actions to chat, APIs, CLI, and MCP clients.

Connect the work
Slack, CRM, docswebhooks and live eventsagent-written connectors
built-ins, live events, or code
Build shared memory
Goal
watch renewal risk
entitiestable
nametypeupdated
Customer Acompany2d
Customer Bperson5h
Customer Cmeeting1h
records humans can inspect and edit
Act anywhere
Team channels
Agent access
CLIMCPAPISDK
Actions
tools + approvals
same memory, same guardrails

Request Flow

Section titled “Request Flow”
  1. User sends a message from Slack, Telegram, WhatsApp, or API.
  2. Gateway receives it, resolves agent settings, and routes a job.
  3. A worker subprocess executes the prompt using the OpenClaw runtime.
  4. Worker uses tools/MCP through gateway-controlled paths.
  5. Gateway streams output back to the platform thread.

Runtime Boundaries

Section titled “Runtime Boundaries”
  • Gateway: orchestration, OAuth, secrets, domain policy, routing — all in the host Node process.
  • Worker: model execution, tools, workspace state — a sandboxed subprocess that never sees real credentials.
  • Postgres (with pgvector): the only external dependency Lobu ever needs. Holds the run queue, agent settings, grants, secrets, chat history, and MCP proxy sessions. Scaffolded projects (lobu init / lobu run) default to an embedded Postgres (PG18 + pgvector, runs in-process), so DATABASE_URL is optional there; only the monorepo make dev requires an external Postgres. There is no Redis anywhere.

Persistent Memory

Section titled “Persistent Memory”

Memory is pluggable per agent. The gateway resolves the default memory plugin from defineConfig({ org }) in lobu.config.ts: when an org is set it wires @lobu/openclaw-plugin (OpenClaw memory calls become Lobu MCP requests through the gateway proxy, cross-session, shared across agents); otherwise it uses @openclaw/native-memory (files in the worker’s local workspace, short-term, not shared). MEMORY_URL is an optional base-endpoint override for custom Lobu deployments.

See Agent Settings → Memory Plugins for the full table, per-agent overrides, and the pluginsConfig schema.

Security-Critical Path

Section titled “Security-Critical Path”
  • Workers never see real credentials. They receive lobu_secret_<uuid> placeholders; the gateway’s secret-proxy swaps in the real keys at egress.
  • Outbound access is controlled via the gateway HTTP proxy and domain policy.
  • MCP credentials are resolved by the gateway proxy. Third-party integration OAuth (GitHub, Google, Linear, etc.) lives in Lobu MCP servers — workers never hold those tokens.