# Getting Started

> Choose between managed community access and self-hosted deployment.

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

## Quick start

```bash
# 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](/reference/lobu-toml/) |
| `agents/*/IDENTITY.md`, `SOUL.md`, `USER.md` | [Agent Workspace](/guides/agent-prompts/) |
| `agents/*/skills/`, `skills/` | [SKILL.md reference](/reference/skill-md/), [Skills](/getting-started/skills/) |
| `agents/*/evals/` | [Evaluations](/guides/evals/) |
| `models/`, `data/` | [Memory](/getting-started/memory/) |
| `docker-compose.yml`, `Dockerfile.worker` | [Deployment](/deployment/docker/) |

## Develop your agent

The fastest way to build your agent is to point a coding agent at the generated project. Open [Claude Code](https://claude.ai/claude-code), [Codex](https://openai.com/index/codex/), [OpenCode](https://opencode.ai), 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:

```bash
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:

```bash
# 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](/reference/cli/) for all available commands.

### Embedded (library)

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

```typescript

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](/deployment/embedding/) 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.