Getting Started

Deploy sandboxed, persistent AI agents to your infrastructure — one isolated agent per user and channel, from a single deploy.

Quick start

# 1. Scaffold and run
npx @lobu/cli@latest init my-agent
cd my-agent && npx @lobu/cli@latest run -d

# 2. Chat with your agent
npx @lobu/cli@latest chat "Hello, what can you do?"

# 3. Run evals to measure quality
npx @lobu/cli@latest eval

Project structure

my-agent/
├── lobu.toml                  # agents, providers, skills, network
├── .env                       # secrets (API keys, OAuth tokens)
├── docker-compose.yml         # Redis + gateway + optional Owletto
├── 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/                # skills scoped to this agent only
│   └── evals/
│       └── ping.yaml          # test cases for agent quality
├── skills/                    # skills shared across all agents
├── models/                    # Owletto entity schemas (if memory enabled)
└── data/                      # Owletto seed entities and relationships

Path	Docs
lobu.toml	lobu.toml reference
agents/*/IDENTITY.md, SOUL.md, USER.md	Agent Workspace
agents/*/skills/, skills/	SKILL.md reference, Skills
agents/*/evals/	Evaluations
models/, data/	Memory
docker-compose.yml, Dockerfile.worker	Deployment

Develop your agent

The fastest way to build your agent is to point a coding agent at the generated project. Open Claude Code, Codex, OpenCode, or any coding agent and paste this prompt:

I am building a Lobu agent in this repository.

Please:
1. Read AGENTS.md, lobu.toml, and agents/my-agent/{IDENTITY,SOUL,USER}.md first.
2. Help me shape the agent behavior by editing those files directly.
3. Use Lobu skills when they make sense: https://lobu.ai/getting-started/skills/
4. Suggest any provider, skill, or connection changes needed in lobu.toml.
5. Keep the project runnable with `npx @lobu/cli@latest run -d`.

Explain what you change and why.

What to ask for

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.toml	”Add GitHub and Linear skills, 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”

After each change, test with:

npx @lobu/cli@latest chat "Hello, can you cancel my subscription?"
npx @lobu/cli@latest eval

Configuration

Lobu supports two configuration approaches depending on how you deploy:

CLI

After init, your project is configured through lobu.toml. Use the CLI to add providers and install starter skills at any time:

# Browse and add providers
npx @lobu/cli@latest providers list
npx @lobu/cli@latest providers add gemini          # prompts for API key, updates lobu.toml + .env

# Install the Lobu starter skill into skills/lobu
npx @lobu/cli@latest skills list
npx @lobu/cli@latest skills add lobu

# Install the Owletto starter skill separately
npx owletto@latest skills add owletto

# Manage secrets
npx @lobu/cli@latest secrets set GEMINI_API_KEY AIza...
npx @lobu/cli@latest secrets list

# Validate and run
npx @lobu/cli@latest validate
npx @lobu/cli@latest run -d

See the CLI Reference for all available commands.

Embedded (library)

When using @lobu/gateway as a library, configure agents in code:

import { Lobu } from "@lobu/gateway";

const lobu = new Lobu({
  redis: process.env.REDIS_URL!,
  agents: [{
    id: "support",
    providers: [{ id: "openai", key: process.env.OPENAI_API_KEY! }],
    skills: ["github"],
  }],
});
await lobu.start();

See Embed in Your App for framework-specific examples.

Both modes expose an admin page at /agents and a REST API at /api/docs for runtime management — adding providers, connections, and viewing agent status.