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
2. 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/.
2. Pick the right AuthType.
3. 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).
4. If lbctl uses the route or capability, check the separate langbot-cli client for compatibility.
5. 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.