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/
│   │   ├── application/    # Unified API: Workspace operation catalog + ExecutionAPI
│   │   ├── 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
docs/                       # public docs site (zh/en/ja), published to langbot.app/docs
dev-docs/                   # internal design notes, contracts, reviews (not published)
plugins/                    # official plugins, released independently of Core
skills/                     # agent skills + lbs QA harness
tests/  tools/  scripts/    # Core tests, regression harness, maintenance scripts
docker/                     # compose / k8s deployment

See "Repository Layout" in the root AGENTS.md for the docs/ vs dev-docs/ rule.

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 capability

1. Implement business logic once in a service under pkg/api/http/service/ (or the owning package) and register it as an Application API operation: allowlist in pkg/api/application/service_operations.py, docs/risk/exposure in operation_docs.py. Design: dev-docs/architecture/application-api.md.
2. Wire each consumer that should support it and note the decision in the PR: HTTP controller in pkg/api/http/controller/groups/ (pick the right AuthType), MCP tool in pkg/api/mcp/server.py + langbot-mcp-ops skill, Workspace assistant/LocalAgent tools, plugin exposure/permissions, and langbot-cli compatibility.
3. If plugins can call it, regenerate the SDK proxy with uv run python scripts/generate_plugin_workspace_api.py and update docs/*/plugin/dev/apis/workspace.mdx / permissions.mdx.
4. Update dev-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. Backend messages use pkg/i18n with all eight locale catalogs; see "Backend Message Language" in AGENTS.md.
• 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.