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.

Architecture

Raw events in. Typed memory out. Agents act.

Connectors stream events into memory. Watchers derive typed entities. Agents read it, talk to users, and act.

Connectors
50+ built-in connectorsany MCP servercustom via connector-sdk
stream events from any source
Memory
events
LLM watcher
entitiestable
nametypeupdated
Customer Acompany2d
Customer Bperson5h
Customer Cmeeting1h
append-only knowledge graph
Agents
Chat bots
Other agents
HTTPMCPSDK
External services
reactions
reach users, or call from code

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.