Install
Note: Pull the public Libra OS Docker image and have a working gateway in under five minutes. This page is for operators standing up a self-hosted instance. If you already have one running and want to point your Anthropic SDK at it, jump to the Anthropic SDK Quickstart instead.
This is the operator path — for teams provisioning Libra OS for the first time, whether for evaluation or production.
⚠️ License Notice
The Libra OS server is provided for evaluation and development use under the Business Source License. Production deployments require a commercial license — contact [email protected] for pricing.
The SDK (Python, CLI, OpenAPI) at
libraos/sdkis MIT-licensed and free to use commercially.
What you'll do
Pull the Docker image from the public registry.
Provide three environment variables (database, JWT secret, LLM API key).
Run a smoke test against
/api/health.
That's the minimum. Optional steps cover docker-compose, Kubernetes, and reverse-proxy setup.
Step 1 — Prerequisites
Docker 20.10+ or any OCI runtime
linux/amd64 and linux/arm64 images are published; pick the one that matches your host
PostgreSQL 14+
Used for users, agents, settings, audit log. SQLite is not supported.
An LLM API key
One of OPENAI_API_KEY (any OpenAI-compatible endpoint), ANTHROPIC_API_KEY, or GOOGLE_API_KEY. A MegaNova-issued key works for all three via OPENAI_API_BASE=https://api.meganova.ai.
≥ 2 GB RAM, ≥ 1 vCPU
Conservative floor for a single-tenant evaluation. Production sizing depends on the tier model split (premium answer model is the dominant cost)
GPU is optional. Embeddings can run via the configured LLM gateway (recommended) or against a local Ollama you already have running. No CUDA or NVIDIA driver setup is required for the gateway path.
Step 2 — Pull the image
The image lives at ghcr.io/libraos/libraos and is public — no GitHub login required.
Choosing a tag:
:v0.1.5 (or any specific version)
Production. Pins to an exact release. Recommended.
:latest
Tracks the most recent stable release. Pre-release tags (-rc, -beta, -alpha) do NOT update :latest.
:v0.1.5-week-2026-05-09 (weekly partner-validation tag)
Bake against new functionality before the production cutover. Weekly and RC tags are pre-1.0 and may include breaking changes.
The full list of available tags lives at GitHub Container Registry → libraos/libraos and on the Releases page.
No GHCR auth needed. The image is public regardless of the source repo's visibility. If a
docker pullfails withdenied: requested access to the resource is denied, your Docker client is sending stale credentials — trydocker logout ghcr.iofirst.
Step 3 — First run
Provide three environment variables and start the container:
The container exposes the API on port 8900. First boot runs database migrations automatically — expect ~5 seconds before /api/health returns 200.
Required environment variables
LIBRA_OS_DATABASE_URL
yes
PostgreSQL connection string. The container does not ship Postgres — point at your own.
LIBRA_OS_JWT_SECRET
yes
≥ 32 hex chars. Used to sign user JWTs. Lose this and all existing tokens become invalid.
OPENAI_API_KEY
yes (or ANTHROPIC_API_KEY/GOOGLE_API_KEY)
LLM provider key. The MegaNova gateway issues a single key that covers all three providers.
OPENAI_API_BASE
recommended
Default https://api.openai.com. Set to https://api.meganova.ai to use MegaNova's multi-provider gateway. On a MegaNova Token Plan, use https://enterprise.api.meganova.ai instead so usage draws the plan allowance — see the Libra OS integration guide.
LIBRA_OS_ADMIN_EMAIL
first boot only
Auto-creates an admin user on a fresh database. Subsequent boots ignore this.
LIBRA_OS_ADMIN_PASSWORD
first boot only
Pair with LIBRA_OS_ADMIN_EMAIL.
A complete env-var reference lives in the Admin Guide.
Step 4 — Smoke test
If all three commands return without error, you have a working Libra OS gateway. The next step is pointing your client at it — see the Anthropic SDK Quickstart.
Optional — Docker Compose
For production deploys, use the pre-built manifests at
libraos/stackinstead of the inline example below. That repo gives you the core (Libra OS + Postgres + SurrealDB) plus optional companion apps (LibreChat chat UI, SearXNG, crawl4ai, Firecrawl, Docling, FlashRank, Phoenix, Hermes) as independent overlay compose files. Required secrets use the fail-fast${VAR:?required - hint}pattern instead of insecure inline defaults.
For a single-host evaluation that also stands up Postgres in the same compose file:
Bring it up:
Production caveat. This compose file is fine for evaluation. For production: don't put
JWT_SECRETandADMIN_PASSWORDin inline literals; use a secrets manager (Docker Secrets, Vault, or Kubernetes Secrets). And put a TLS-terminating reverse proxy (Caddy, nginx, Traefik) in front — Libra OS speaks plain HTTP on:8900.
Optional — Behind a reverse proxy
The container speaks plain HTTP. Terminate TLS at your edge.
Caddy (the simplest path — automatic Let's Encrypt):
nginx (when you already have nginx infra):
The streaming-related flags are required for /v1/messages and /v1/chat/completions to work over HTTP/2 + Cloudflare. Without them, Cloudflare returns ERR_HTTP2_PROTOCOL_ERROR mid-stream.
Worked example — minimum viable instance
The smallest working setup, end to end:
Open http://localhost:8900/ in a browser to see the dashboard, log in with the admin credentials, and start binding collections to agents per the Admin Guide.
Troubleshooting
docker pull fails with manifest unknown or not found
The tag you requested doesn't exist. Check the GHCR package page for available tags. Pre-release tags use -rcN / -betaN suffixes; stable releases are bare semver (v0.1.19).
docker pull fails with denied: requested access to the resource is denied
Your Docker client is sending stale GHCR credentials for a different package. Run docker logout ghcr.io and retry.
libraos container exits immediately with failed to connect to database
The LIBRA_OS_DATABASE_URL value isn't reachable from inside the container. Common causes:
localhostinside a container points to the container itself, not the host. Usehost.docker.internal(Docker Desktop) or the host's LAN IP.The Postgres container isn't accepting external connections — pass
-p 5432:5432when running it.Wrong username/password — Postgres logs the rejection at startup.
Container starts, /api/health returns 200, but /v1/messages returns 500 with no LLM API keys configured
Either no provider key is set, or the key isn't reaching the container. Confirm with docker exec libraos env | grep -E 'OPENAI|ANTHROPIC|GOOGLE'.
HTTP 401 — invalid token: token expired after a few hours
JWT lifetime defaults to short. The Anthropic SDK and dashboard both auto-refresh; bare curl doesn't. Re-issue via POST /api/auth/login or generate a long-lived service token from the admin dashboard.
HTTP 426 Upgrade Required on /v1/agents or /v1/sessions
Managed Agents endpoints require the beta header. Add -H "anthropic-beta: managed-agents-2026-04-01" to your request. The Messages API at /v1/messages does not require it — it's GA.
Known limitations
No SQLite. Postgres is required. The schema uses Postgres-specific features (JSONB, partial indexes, advisory locks). SQLite is not on the roadmap.
No bundled Ollama. The image doesn't ship local LLM weights. Set
OPENAI_API_BASEto a gateway you trust (MegaNova or your own); for fully on-prem inference, run Ollama separately and pointOPENAI_API_BASEat it.Stateful upgrades. Schema migrations run on container start. For multi-replica deployments, run one replica at a time across an upgrade boundary; concurrent migrations on the same database race.
No multi-tenant isolation across instances. Per-user filesystem and per-tenant agent overrides exist within an instance; running tenants on truly-isolated instances is the path for hard tenancy boundaries.
These are intentional v0 scope cuts.
Next steps
Anthropic SDK Quickstart — point your existing Anthropic-SDK code at the gateway you just installed
Documents & Knowledge — upload files so agents can retrieve from them
Admin Guide — agent-to-collection bindings, system status, troubleshooting
Releases — what's new in each version, migration notes
libraos/stack— production-grade compose manifests, plus 8 optional companion apps (LibreChat chat UI, SearXNG, crawl4ai, Firecrawl, Docling, FlashRank, Phoenix, Hermes)
Last updated