version: "1.0.0" name: langbot-dev description: Develop, build, and debug the LangBot core backend and web frontend. Use when working inside the LangBot repository — backend (Python/Quart, src/langbot/pkg), the Vite/React web UI, HTTP API controllers/services, Alembic migrations, or the MCP server. Covers the dev environment (uv, pnpm), repo layout, the API auth model (user token / API key / global key), adding API endpoints, and the rule that API changes must update the MCP server and skills. Triggers on "langbot backend", "langbot dev", "langbot api", "add langbot endpoint", "langbot migration".

LangBot Core Development

This skill covers developing the LangBot core (the main repo), distinct from plugin development (see langbot-plugin-dev) and deployment (langbot-deploy).

Stack

• Backend: Python >=3.11,<4.0, deps via uv. Framework: Quart (async

Flask). Serves the HTTP API + pre-built web UI on http://127.0.0.1:5300.

• Frontend (web/): Vite + React Router 7 + shadcn/ui + Tailwind,

managed by pnpm. Dev server on :3000. (NOT Next.js — dev script is vite.)

Dev environment

# Backend
pip install uv
uv sync --dev
uv run main.py            # API + UI on http://127.0.0.1:5300
 
# Frontend (separate terminal)
cd web
cp .env.example .env
pnpm install
pnpm dev                  # http://127.0.0.1:3000 (reads VITE_API_BASE_URL)
 
# Lint/format hooks (CI runs the same checks)
uv run pre-commit install

First run generates data/config.yaml; DB defaults to SQLite (PostgreSQL supported). Migrations run automatically on startup.

Repo layout (key paths)

src/langbot/
├── __main__.py             # entrypoint, CLI flags (--standalone-runtime/-box/--debug)
├── pkg/
│   ├── api/
│   │   ├── http/           # Quart controllers + services
│   │   │   ├── controller/groups/   # route groups (@group.group_class)
│   │   │   └── service/             # business logic (called by controllers AND MCP)
│   │   └── mcp/            # MCP server (server.py = tools, mount.py = ASGI dispatch)
│   ├── core/               # app bootstrap, stages, task manager
│   ├── platform/ provider/ pipeline/ plugin/ box/ skill/ rag/ vector/
│   ├── command/ persistence/ storage/ config/ entity/ telemetry/
│   └── templates/config.yaml        # config template (top-level: api, system, plugin, box, space...)
├── web/                    # Vite SPA
└── docker/                 # compose deployment

HTTP API auth model

Route auth is declared per-route via AuthType in pkg/api/http/controller/group.py:

• NONE — public.
• USER_TOKEN — web UI JWT (Authorization: Bearer <jwt>).
• API_KEY — X-API-Key or Authorization: Bearer <key>.
• USER_TOKEN_OR_API_KEY — either.

Authenticated routes receive an immutable RequestContext containing the principal, authorized Workspace membership, fixed-role permissions, instance, request id, and placement generation. A browser's X-Workspace-Id is only a selector and is always checked against the Account membership. Tenant services must accept this context (or an explicit trusted execution context) and fail closed when it is absent.

API-key authentication accepts:

1. the global key from config.yaml api.global_api_key only for a

community instance with exactly one local Workspace, then

1. web-UI keys whose one-time lbk_ secret is stored only as a hash and is

bound to one Workspace, explicit scopes, status, and optional expiry.

An API key derives its Workspace from the key record and ignores a caller's Workspace selector. Public Bot/Webhook routes similarly derive Workspace from the opaque owning resource rather than a header.

Route groups self-register via @group.group_class(name, path) and are discovered by importutil.import_modules_in_pkg.

Adding an API endpoint

1. Add/extend a controller in pkg/api/http/controller/groups/ and the matching

service method in pkg/api/http/service/.

1. Pick the right AuthType.
2. **If the endpoint should be agent-accessible, add/adjust the matching MCP tool

in pkg/api/mcp/server.py and update the langbot-mcp-ops skill.** API and MCP surface must stay aligned (see AGENTS.md).

1. If lbctl uses the route or capability, check the separate

`langbot-cli` client for compatibility.

1. Update docs/service-api-openapi.json if you maintain the OpenAPI overview.

Database migrations (Alembic)

Single migration set supports SQLite + PostgreSQL. Files in src/langbot/pkg/persistence/alembic/versions/.

# From project root (needs data/config.yaml)
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "description"

Standards

• All code comments/docstrings in English; user-facing strings need i18n

(en_US + zh_Hans minimum, ja_JP where present).

• Consider toC and toB compatibility + security.
• Commit format: <type>(<scope>): <subject> (feat/fix/docs/refactor/...).

Tests

uv run pytest tests/unit_tests -q          # unit tests
uv run pytest tests/unit_tests/api -q      # API service tests
uv run python tests/manual/mcp_smoke.py    # MCP server e2e smoke

See also

• langbot-plugin-dev — plugin SDK / runtime development.
• langbot-testing — WebUI/e2e QA harness (bin/lbs).
• langbot-deploy — Docker/compose deployment + config.
• langbot-mcp-ops — operating the LangBot MCP server.
• `langbot-cli` — lbctl, a standalone Service API client for managing running Workspaces.