Librebase
Repository (origin): gitlab.lilangverse.xyz/librebase-official/librebase — GitHub is a read-only mirror.
Librebase is the open data platform powered by lidb — a Supabase-shaped stack with org/project/database workflows and a web console (Librebase Studio).
This repository is the canonical product home: platform code, Studio UI, docs, and Cursor agent rules.
Brand (Figma)
The current blue bird identity is maintained in Figma. To sync logo and color tokens into Studio and docs, see docs/brand/FIGMA.md.
Paid features
lidb and Librebase Studio are monetized product surfaces. Billing/entitlement enforcement is planned; launch paths include TODO gates in project-runtime.ts. See .cursor/rules/librebase-product.mdc for agent guidance.
Repository layout
| Path | Purpose |
|---|
data-studio-ui/ | Platform and Studio UI (Next.js) |
scripts/ | lidb embed lifecycle (lidb_engine.py) |
docs/ | Architecture and CLI/database docs |
.cursor/rules/ | Cursor agent product context |
Instance & project model
Librebase supports dedicated (1 instance → 1 project, default) and shared (1 instance → N projects) deployment. See docs/architecture-instances.md.
Studio persistence (instances + projects JSON) lives under:
- Linux/macOS:
~/.local/share/librebase/studio
- Windows:
%LOCALAPPDATA%\librebase\studio
Override with LIBREBASE_STUDIO_DATA_DIR.
For AI agents (MCP)
Librebase exposes a hosted MCP endpoint — no local repo needed:
- Auto-discover:
GET https://app.librebase.xyz/.well-known/mcp.json
- Sign in: device flow (
auth_start / auth_poll on POST https://app.librebase.xyz/api/mcp) — a human approves once in the browser; the agent receives an lb_agt_* token.
- Connect: send
Authorization: Bearer <token> on every other tool call (org_whoami, project_list, instance_list, KMS tools, etc.).
Optional stdio bridge (repo checkout or future librebase-mcp package) — same contract as @librebase/mcp:
| Variable | Purpose |
|---|
LIBREBASE_MCP_URL | Hosted MCP JSON-RPC URL (default https://app.librebase.xyz/api/mcp) |
LIBREBASE_MCP_TOKEN | Optional lb_mcp_* / lb_agt_* bearer when skipping device flow |
{
"mcpServers": {
"librebase": {
"command": "python3",
"args": ["-m", "librebase_mcp"],
"env": {
"LIBREBASE_MCP_URL": "https://app.librebase.xyz/api/mcp",
"LIBREBASE_MCP_TOKEN": "lb_mcp_…"
}
}
}
}
Details: mcp/README.md · https://app.librebase.xyz/for-agents · https://app.librebase.xyz/llms.txt
Self-hosting
Run Studio, Admin API, and KMS on your own VM with Docker Compose. See docs/self-hosting.md and deploy/compose/.env.example.
Development
From the repo root:
cd data-studio-ui
npm install
npm run dev
Studio dev server: http://127.0.0.1:54324
Cloud workflow routes:
| Route | Purpose |
|---|
/ | Projects grid (primary nav) |
/instances | Instances list + health |
/projects/new | Create project (new instance vs existing) |
/projects/:id | Project home + launch database |
Local runtime without lidb: Studio defaults to LIDB_RUNTIME_MODE=dev, which starts scripts/dev_runtime_stub.py via scripts/lidb_engine.py when LIDB_ROOT is unset.
Production local runtime: set LIDB_ROOT to a lidb checkout and ensure lis is on PATH.
Kubernetes
Studio can target a Kubernetes cluster instead of local processes:
$env:LIBREBASE_RUNTIME = "kubernetes"
$env:KUBECONFIG = "C:\path\to\kubeconfig"
| Path | Purpose |
|---|
deploy/docker/lidb-runtime/ | Dev runtime Docker image (librebase/lidb-runtime:dev) |
deploy/kubernetes/ | Reference manifests (dedicated + shared) |
deploy/helm/librebase-instance/ | Helm chart for manual installs |
docs/kubernetes.md | Architecture, kind/minikube steps, Studio flow |
data-studio-ui/lib/k8s-provisioner.ts | Provisioner used by API and launch routes |
Build the runtime image, load into kind/minikube, then create a project with Deploy to Kubernetes on /projects/new (or set LIBREBASE_RUNTIME=kubernetes globally):
.\deploy\docker\lidb-runtime\build.ps1
kind load docker-image librebase/lidb-runtime:dev --name librebase
$env:LIBREBASE_K8S_IMAGE = "librebase/lidb-runtime:dev"
Health stays honest: green only when probes see real open ports.
Testing
cd data-studio-ui
npm test
npm run test:coverage
test:coverage reports line coverage for lib/** (30% line threshold locally). CI runs the same report without failing on coverage thresholds while the suite grows.
| Layer | Tool | Focus |
|---|
| Studio stores / bridge | Vitest | instances-store, projects-store, dedicated vs shared |
| lidb embed / dev runtime | Python unittest | lidb_engine.py lifecycle, port probes |
| E2E | Playwright (planned) | create flow, Instances view, honest health UI |
cd data-studio-ui && npm test
python -m unittest discover -s tests -p "test_*.py"
GitHub Actions (.github/workflows/test.yml) runs on push and PR to main: Vitest + Python tests + npm run build in data-studio-ui (Node 20).
licontainer (Li Container Engine)
Pure Li OCI engine — licontainer/ contains only .li packages. No Rust, no C in librebase. Trusted OCI impl merges into lic (like li-net).
export LIC_ROOT=/path/to/lic
./licontainer/scripts/build-li.sh
| Path | Purpose |
|---|
licontainer/packages/ | Li workspace: run, daemon, CLI, img, cri |
licontainer/PURE-LI-POLICY.md | Repo language policy |
docs/rfc-container-trusted-surface.md | Upstream lic merge RFC |
Studio: LIBREBASE_RUNTIME=licontainer. K8s: Helm containerRuntime: licontainer.
CI: .github/workflows/licontainer-build.yml (pure Li lic build only).
