Getting Started

Lobu is the open-source backend for organizational agents. Each user or channel gets an isolated runtime while connections, permissions, events, and entity memory stay shared at the organization level.

Quick start

npx @lobu/cli@latest init my-agent
cd my-agent
npx @lobu/cli@latest run

# In another terminal
npx @lobu/cli@latest chat "Hello, what can you do?"

Lobu uses embedded PostgreSQL by default. Set DATABASE_URL only when you want an external database.

The model in one minute

connector definition → connection → feed → run → event → entity memory
                                                  ↓
                                  agent or watcher reads and acts
                                                  ↓
                                             more events

• A connector definition is reusable integration code.
• A connection is one configured account, installation, webhook, or channel.
• A feed is a collected, streaming, or virtual data stream.
• A run records one sync, agent turn, watcher window, schedule, or action.
• An event is durable evidence, including engagement, corrections, and outcomes.
• An entity is shared organizational state built from those events.
• An agent combines persona, skills, tools, guardrails, inference, and execution.
• A watcher reads new events incrementally and can remember, notify, or act.

Read Concepts and architecture before building a larger system.

Project layout

my-agent/
├── lobu.config.ts
├── .env
├── AGENTS.md
├── agents/my-agent/
│   ├── IDENTITY.md
│   ├── SOUL.md
│   ├── USER.md
│   ├── skills/internal-api/SKILL.md
│   └── evals/promptfooconfig.yaml
├── github.connector.ts
└── notify.reaction.ts

| Path | Owns | | --- | --- | | lobu.config.ts | Agents, providers, environments, connections, tools, guardrails, entities, and watchers | | IDENTITY.md | Who the agent is | | SOUL.md | Rules, workflows, constraints, and tone | | USER.md | Shared user or deployment context | | SKILL.md | Reusable instructions and capability requirements | | *.connector.ts | Integration code that produces events or executes source actions | | *.reaction.ts | Typed code that runs after watcher extraction | | evals/ | Regression and quality tests |

How files are loaded

lobu.config.ts is the desired-state entrypoint. Files are included only when referenced:

connectorFromFile("./github.connector.ts");
reactionFromFile("./notify.reaction.ts");
skillFromFile("./agents/my-agent/skills/internal-api");
defineAgent({ dir: "./agents/my-agent" });

There is no directory auto-discovery.

• lobu run loads the config and referenced files locally.
• lobu apply validates the project, bundles referenced code, and syncs the desired state to Lobu Cloud.

Build in layers

1. Define the agent

Use workspace files for identity and behavior. Keep operator-controlled configuration in lobu.config.ts. See Agent workspace.

2. Add capability and policy

• Skills teach reusable procedures.
• Tool policy controls tool visibility and approval overrides.
• Guardrails inspect input, output, and tool calls independently of the prompt.
• Providers select inference; environments select execution.

3. Connect systems

Use a built-in connector or add TypeScript with connectorFromFile(...). A connector definition becomes available to configure as connections and feeds. See Connector SDK.

4. Add shared memory and watchers

Events can attach to one or more typed entities. Watchers process new event windows, maintain state, notify people, or take approved actions. See Memory.

5. Add evals before increasing autonomy

bun add -D promptfoo @lobu/promptfoo-provider
export LOBU_TOKEN=$(npx @lobu/cli@latest token --raw)
bunx promptfoo eval -c agents/my-agent/evals/promptfooconfig.yaml

See Evaluations.

Develop with a coding agent

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

Then ask it to edit the correct layer:

| Goal | Edit | | --- | --- | | Change role or tone | IDENTITY.md or SOUL.md | | Add a reusable procedure | SKILL.md and the agent’s skills list | | Connect a new system | lobu.config.ts or a connector file | | Restrict tools or network | Agent config in lobu.config.ts | | Add shared knowledge | Entity types and watchers | | Prevent a regression | agents/<id>/evals/ |

Apply to Lobu Cloud

npx @lobu/cli@latest login
npx @lobu/cli@latest validate
npx @lobu/cli@latest apply --org my-org

See lobu apply and the lobu.config.ts reference.