Getting Started

Lobu is the open-source backend for multi-user AI agents. It gives every user or channel an isolated agent workspace with connected sources, shared memory, and per-user OAuth isolation.

Quick start

Lobu boots as a single Node process. By default it uses an embedded Postgres (PG18 + pgvector), so you can start without Docker or a separate Postgres. Set DATABASE_URL only when you want to use an external Postgres.

# 1. Scaffold
npx @lobu/cli@latest init my-agent
cd my-agent

# 2. Boot locally (uses embedded Postgres by default)
npx @lobu/cli@latest run

# 3. Chat with your agent (in another terminal)
npx @lobu/cli@latest chat "Hello, what can you do?"

# 4. Run evals to measure quality (uses promptfoo via @lobu/promptfoo-provider)
bun add -D promptfoo @lobu/promptfoo-provider
LOBU_TOKEN=$(npx @lobu/cli@latest token) bunx promptfoo eval \
  -c agents/my-agent/evals/promptfooconfig.yaml

Project structure

my-agent/
├── lobu.config.ts             # agents, providers, network, memory schema (TypeScript)
├── package.json               # declares @lobu/cli/config + @lobu/connector-sdk
├── tsconfig.json
├── .env                       # secrets (API keys, optional DATABASE_URL)
├── AGENTS.md                  # briefing for coding agents
├── README.md
├── TESTING.md
├── agents/my-agent/
│   ├── IDENTITY.md            # who the agent is
│   ├── SOUL.md                # instructions, rules, workflows
│   ├── USER.md                # per-user context and preferences
│   ├── skills/                # SKILL.md files, referenced via skillFromFile
│   └── evals/
│       └── promptfooconfig.yaml  # test cases for agent quality (promptfoo)
├── my-feed.connector.ts       # custom connector, referenced via connectorFromFile
├── my-watcher.reaction.ts     # watcher reaction, referenced via reaction:
└── data/                      # local runtime data; memory seeds when enabled

Connectors, reaction scripts, and skill files are referenced explicitly from lobu.config.ts (connectorFromFile / defineWatcher({ reaction }) / skillFromFile), so they can live anywhere — next to the config for small agents, or in folders as you grow. There is no directory auto-discovery.

The memory schema (entity types, relationship types, watchers) lives directly in lobu.config.ts via defineEntityType / defineRelationshipType / defineWatcher.

Path	Docs
lobu.config.ts	lobu.config.ts reference
agents/*/IDENTITY.md, SOUL.md, USER.md	Agent Workspace
*/SKILL.md (via skillFromFile)	SKILL.md reference, Skills
agents/*/evals/	Evaluations
*.connector.ts (via connectorFromFile)	Connector SDK
.env	CLI reference

Develop your agent

Install the Lobu skill into your coding agent so it already understands the project layout, lobu.config.ts, evals, memory wiring, and client setup:

npx skills add lobu-ai/lobu --skill lobu

See Skills for which coding agents this supports and how to scope it. With the skill installed, open your coding agent in the project and shape behavior by editing agents/my-agent/{IDENTITY,SOUL,USER}.md, lobu.config.ts, and agents/my-agent/evals/promptfooconfig.yaml, then re-run npx @lobu/cli@latest chat "…" and bunx promptfoo eval -c agents/my-agent/evals/promptfooconfig.yaml after each change.

File	What to ask for
agents/my-agent/IDENTITY.md	”Make this a customer support agent for Acme Corp”
agents/my-agent/SOUL.md	”Add rules: never share pricing, always confirm before cancellations”
agents/my-agent/USER.md	”Set timezone to US/Pacific, company plan is Enterprise”
lobu.config.ts	”Add a GitHub MCP server and allow github.com and api.linear.app”
agents/my-agent/evals/	”Write an eval that tests the agent follows the cancellation rule”
agents/my-agent/skills/	”Create a custom skill for our internal API”

Configuration

lobu.config.ts plus the files under agents/<id>/ are the source of truth: agents, providers, network policy, tool policy, MCP servers, and (optionally) the memory schema. lobu.config.ts is a TypeScript module that default-exports defineConfig({...}) and imports its authoring functions from @lobu/cli/config. Edit it locally and lobu run picks it up immediately.

To run an agent on Lobu Cloud, push the same project up with lobu apply:

npx @lobu/cli@latest login              # authenticate
npx @lobu/cli@latest validate           # check lobu.config.ts + agent files
npx @lobu/cli@latest apply --org my-org # sync to your Cloud org

The Cloud web app and the CLI talk to the same org-scoped REST API, so anything you do in the UI (add providers, connections, skills; view agent status) you can also drive from lobu.config.ts + lobu apply. See the CLI Reference and lobu apply for the full surface.