> For the complete documentation index, see [llms.txt](https://docs.meganova.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.meganova.ai/libra-os/releases.md).

# Releases

> **Note:** This page is a curated reader-facing changelog — what's new, what's broken, what to do when upgrading. Raw per-commit changelogs live on the [Releases page on GitHub](https://github.com/libraos/sdk/releases) and in `CHANGELOG.md` on the SDK repo.

> ⚠️ **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 <contact@meganova.ai> for pricing.
>
> The **SDK** (Python, CLI, OpenAPI) is **MIT-licensed** and free to use commercially.

This is the operator path — for teams deciding whether to pull a new image and migration notes when they do.

## Where the canonical artifacts live

| Artifact                               | Location                                                                                                                                                 |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Server Docker image                    | `ghcr.io/libraos/libraos:<version>` for v0.1.13 and later; earlier tags stay on `ghcr.io/meganovaai/nova-os:<version>`. Both public, no auth required    |
| GitHub Release notes (raw, per-commit) | [`libraos/sdk` releases](https://github.com/libraos/sdk/releases)                                                                                        |
| OpenAPI spec for the version           | [`libraos/sdk/openapi/libra-os-partner.v1.yaml`](https://github.com/libraos/sdk/blob/main/openapi/libra-os-partner.v1.yaml) (tagged at the same version) |
| Source                                 | private — partners do not build from source                                                                                                              |

## Versioning policy

Libra OS follows semantic versioning with explicit pre-release tags:

| Tag shape                                                | Stability                                                                                                                                                                    | `:latest` updates? |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `vX.Y.Z` (e.g. `v0.1.5`)                                 | Stable. Recommended for production.                                                                                                                                          | yes                |
| `vX.Y.Z-week-YYYY-MM-DD` (e.g. `v0.1.5-week-2026-05-09`) | Partner-validation weekly cut on the active line. Cumulative changes from the prior weekly + delta of the past week. Used by partners running active integration validation. | no                 |
| `vX.Y.Z-rcN` (e.g. `v0.1.4-rc2`)                         | Release candidate. Feature-complete for the upcoming `vX.Y.Z` but not yet promoted.                                                                                          | no                 |
| `vX.Y.Z-betaN` / `-alphaN`                               | Pre-release. Breaking changes possible.                                                                                                                                      | no                 |

`:latest` always points at the most recent stable release. Weekly, RC, and beta tags are addressable by exact name only.

***

## v0.1.5 — 2026-05-04 *(force-updated 2026-05-05 to roll up rounds 5-6)*

**Image:** `ghcr.io/meganovaai/nova-os:v0.1.5` (also pulled by `:latest`) **Tag SHA:** `00ee958` (identical to `v0.1.5-week-2026-05-09` — stable and weekly collapsed on 2026-05-05)

> **Stable `v0.1.5` was force-pushed forward on 2026-05-05 to absorb the rounds 5-6 in-flight work that landed on the weekly tag.** Stable and weekly now point at the same SHA; `:latest` follows `:v0.1.5` per the release-image workflow rule. Partner-validation hit 7/7 against the round-6 weekly on EqualDocs' aifirm suite, so holding stable behind weekly served no operator goal.
>
> **What's in the rolled-up `v0.1.5` (delta from the original 2026-05-04 cut):**
>
> * **Partner-prefix wrappers** under `/v1/managed/*` — documents, knowledge, hooks, filesystem, users, settings, sessions. SDK `c.*` modules ship in lockstep at OpenAPI alpha.3-alpha.4.
> * **Persona manifest API** — `/agents/v1/personas` with ETag/If-None-Match round-trip; `/agents/v1/personas/:id` for single-entry lookups. Boot-time contract surface so partners stop mirroring nova-os YAML in their own code. SDK `c.personas` ships at OpenAPI alpha.5.
> * **Gateway-safe defaults** — `OPENAI_MODEL=gemini/gemini-2.5-flash` ([#197](https://github.com/libraos/libraos/issues/197)/[#198](https://github.com/libraos/libraos/pull/198)) and `OPENAI_API_BASE=https://api.meganova.ai` ([#216](https://github.com/libraos/libraos/pull/216)). Bare `docker run` deployments with just `OPENAI_API_KEY=msk_...` now work without further env-var configuration. Override paths unchanged: `-e OPENAI_API_BASE=https://api.openai.com` for OpenAI direct, `-e OPENAI_MODEL=<vendor>/<model>` for explicit model selection. Key shapes (`sk-...` vs `msk_...`) make misconfiguration surface at deploy time.
> * **`web_search_config` per-call resolution** — persona `web_search_config` is now resolved per-invocation on `skill_deep_research` (was silently ignored before, [#200](https://github.com/libraos/libraos/issues/200)/[#212](https://github.com/libraos/libraos/pull/212)). YAML field rename: `backend` → `primary_backend`, `fallback` → `fallback_chain` (non-breaking — zero personas use the old names).
> * **Tavily/MEGANOVA\_API\_KEY follow-ups** — Tavily-primary `FallbackSearcher` no longer burns 5-15s of redundant Firecrawl fetches per multi-aspect query ([#213](https://github.com/libraos/libraos/issues/213)). `MEGANOVA_API_KEY` accepted as alias for `MEGANOVA_CLOUD_KEY` ([#214](https://github.com/libraos/libraos/issues/214)).
> * **Permission slice-1** — `permission_mode` + plan mode (closes [#183](https://github.com/libraos/libraos/issues/183) slice-1 + [#184](https://github.com/libraos/libraos/issues/184)).
>
> **Operator gotcha** — the admin-cred fail-fast guardrail (`LIBRA_OS_ADMIN_EMAIL` / `LIBRA_OS_ADMIN_PASSWORD` must be non-default, or set `LIBRA_OS_ALLOW_INSECURE_DEFAULTS=1` for local dev only) catches deployments running on leaked-default creds. The guardrail isn't new — it's been in every release tag — but it's a common first-time-pull surprise. Partner pin docs should mention it.
>
> See the [GitHub release page](https://github.com/libraos/libraos/releases/tag/v0.1.5) for the full force-update history (the weekly tag rolled through 6 rounds before stable absorbed everything).

### Highlights

* **Brain dispatch contract.** Agents can now signal partner-side intent — render inline, navigate to a partner-defined route, or ask for clarification — through three structured `route_hint` kinds emitted on every reply. Surfaces consistently on JSON responses, SSE streams, and the Anthropic-compat metadata channel. Partners register URL templates per agent via the new `route_templates:` frontmatter section, validated at server boot. Partners that don't care about route hints can ignore the field — no required migration.
* **Per-agent planner-skip.** Classifier-style and triage personas can now declare `triage.default_brain: never` in YAML frontmatter to bypass the brain planner entirely, going directly to a single-LLM call. \~2× latency reduction (5s → 2.5s/turn) on routes where the planner adds no signal. Documented as a first-class agent-design convention.
* **Weekly-tag cadence.** Production `vX.Y.Z` releases now follow a weekly partner-validation tag (`vX.Y.Z-week-YYYY-MM-DD`) on the active line. Partners running active integration validation pin to the weekly tag; production cutover happens on the un-suffixed `vX.Y.Z` after a smoke gate. See [Versioning policy](#versioning-policy).

### Migration notes

**No mandatory migration.** The `route_hint` field is opt-in — partners that don't read it see no change. Partners that want to start consuming dispatch hints can do so incrementally per intent (`render_inline`, `navigate_to:<template>`, `ask_clarification:<reason>`) — there is no all-or-nothing flag day. Schema migrations run automatically on first boot.

If you maintain partner agent definitions in `data/agents/*.md`, two opt-in YAML keys are now available:

* `route_templates:` — register the URL templates Brain will fill into `navigate_to:` route hints.
* `triage.default_brain: never` — opt the persona out of the planner cascade.

Both default to off; existing agent files continue to work unchanged.

### Cadence going forward

The next weekly tag on the v0.1.5 line is `v0.1.5-week-2026-05-16`. Subsequent production `v0.1.x` cuts happen after a six-probe smoke gate against the rebuilt master binary; partners running production should track the un-suffixed `vX.Y.Z` tags only.

***

## v0.1.4 — 2026-05-01

**Image:** `ghcr.io/meganovaai/nova-os:v0.1.4` (see [available tags](https://github.com/orgs/libraos/packages/container/package/libraos))

### Highlights

* **Anthropic Managed Agents API compatibility.** The full `/v1/agents`, `/v1/sessions`, `/v1/messages` surface is implemented. Partner code targeting `Anthropic(base_url=...)` works unchanged for the bare Messages API and the Claude Agent SDK; the beta Managed Agents endpoints are reachable behind the `anthropic-beta: managed-agents-2026-04-01` header.
* **Per-agent + per-call model overrides.** Agents declare a `model:` field; per-call `metadata.llm_model` (chat-completions endpoint) or top-level `model` (messages endpoint) overrides at the request boundary. Settings UI exposes the four model tiers (Answer, Skill, Brain, Memory Worker). See [Anthropic SDK Quickstart → Step 5](/libra-os/anthropic-sdk-quickstart.md) for the full layered routing model.
* **Per-agent structured output (`output_type`).** Agents declare a JSON Schema 2020-12 contract via frontmatter; assistant messages are validated before returning. Three violation modes (`error` / `log` / `repair`).
* **Filesystem-as-state for agents.** Per-tenant virtual filesystem with AES-256-GCM encryption at rest and quotas. Six tools auto-registered when an agent declares `filesystem.enabled` in frontmatter.
* **Lifecycle hooks for agents.** Nine HTTP-only events fire at canonical points in the agent loop. HMAC-signed, sync/async, multi-handler chains.
* **Public Docker image.** Server now publishes to `ghcr.io/libraos/libraos` automatically on every release tag. Multi-arch (`linux/amd64` + `linux/arm64`).

### Notable fixes

* **Model name prefix validation.** POST/PUT `/v1/agents` and PUT `/api/config/settings` now reject bare model names without a `<provider>/` prefix. Bare names route to no provider and 404 at chat time on the MegaNova gateway. See the [install guide](/libra-os/install.md) for the convention.
* **CJK-mixed query identifier extraction.** Retrieval was missing identifiers (doc IDs, SKUs, case\_ids) embedded inside Chinese-language questions because the keyword tokenizer split on whitespace. Now extracts Latin/alphanumeric runs ≥4 chars from any query as additional keywords.
* **Vertex AI tool-schema rejection.** Two tool declarations (`create_xlsx`, `create_docx`) were missing `items` on `type: "array"` properties, which Vertex AI strictly enforces. Manifested as misleading "unable to reach upstream endpoints" 400s on Gemini-routed traffic.
* **Knowledge bindings runtime bridge.** Personas with declared `knowledge_bindings` now actually retrieve from those collections at chat time. Pre-fix the field was persisted but ignored by the chat enrichment path.

### Migration notes

**No mandatory migration.** Schema migrations run automatically on first boot. Two operational follow-ups worth doing post-upgrade:

1. **Audit `settings.*_model` keys for bare model names.** Pre-v0.1.4 you may have a bare value like `claude-opus-4-7` in `answer_model`; that now fails validation and silently 404s on the gateway. Re-PUT with a `<provider>/` prefix:

   ```bash
   curl -X PUT https://libra-os.your-company.example/api/config/settings \
     -H "Authorization: Bearer $JWT" \
     -H "Content-Type: application/json" \
     -d '{"answer_model": "anthropic/claude-opus-4-7"}'
   ```
2. **Re-sync persona definitions if you use the `data/agents/*.md` source-of-truth pattern.** The C1 schema added `agent_type`, `brain`, `capabilities`, `max_turns`, `output_type`, and `knowledge_bindings` fields. Files written by pre-v0.1.4 deploys lack these and surface as empty in the dashboard until re-synced.

### Out of scope (deferred to v0.2 / later)

* TypeScript / Rust / Go SDK client libraries (the OpenAPI spec lets partners codegen if they need to before the official ones land)
* Multi-tenant cloud-hosted Libra OS as the SDK's default target (v1 is partner-self-hosted)
* gRPC / WebSocket transport
* LoRA / finetune surface

***

## v0.1.3 — 2026-04-20

**Image:** `ghcr.io/meganovaai/nova-os:v0.1.3` *(retroactive — image first published on the v0.1.4-rc cycle)*

### Highlights

* **AI Firewall live in the agent path.** Six deterministic blocks (firewall, canonicalizer, date-normalizer, redactor, allowlist, secret-guard) gate every LLM call. Each toggleable at runtime via `POST /api/firewall/enabled`.
* **Adaptive `skill_web_research` agent.** Three-tier system prompt (SHALLOW/MEDIUM/DEEP) decides effort based on question complexity. Routes through `search_web`, `fetch_url`, `research_query`, `deep_research`.
* **Chat fast-path mode.** `?fast=true` swaps a `PersonaAgent` for its primary skill, skipping brain planner + mesh cascade. \~10s p95 vs minutes through the planner.
* **MegaNova Cloud search client.** Activates when `MEGANOVA_CLOUD_KEY` is set; preferred default in `DefaultSearcher()` with full BYO-keys fallthrough.
* **i18n server-side foundation.** `LIBRA_OS_ENABLED_LOCALES` env var, `GET /api/config/locales`, nullable `locale` column on `nova_users`.

### Migration notes

No breaking changes. Existing v0.1.2 deployments roll forward by replacing the binary.

***

## v0.1.2 — 2026-04-16

**Image:** `ghcr.io/meganovaai/nova-os:v0.1.2` *(retroactive)*

### Highlights

* **Knowledge collections — second pass.** Bindings cleanup, ingest pipeline hardening, retrieval-quality fixes for hybrid CJK queries.
* **Report generator polish.** Three-tier model split (Brain / Skill / Answer) cuts per-report cost roughly six-fold versus running everything on the premium tier.
* **Dashboard layout refresh.** Agent detail page gains the per-agent Configuration card.

***

## v0.1.1 — 2026-04-16

**Image:** `ghcr.io/meganovaai/nova-os:v0.1.1` *(retroactive)*

### Highlights

* Hotfix release. Fast-follow on v0.1.0 to address bugs surfaced during initial deploy testing.

***

## v0.1.0 — 2026-04-15

**Image:** `ghcr.io/meganovaai/nova-os:v0.1.0` *(retroactive)*

### Highlights

* **First public-tagged release.** Establishes the v0.1.x line, semver policy, and the Docker image distribution pattern.
* Single-binary Go server with PostgreSQL persistence + SurrealDB knowledge store + observational memory.
* 23 agents and 36 tools shipped out of the box.

***

## Pulling a specific release

```bash
# Pin to an exact version (recommended for production)
docker pull ghcr.io/libraos/libraos:v0.1.19

# Track the most recent stable release (auto-skips RCs)
docker pull ghcr.io/libraos/libraos:latest

# Pull a weekly pre-release for partner validation
docker pull ghcr.io/libraos/libraos:v0.1.19-week-2026-09-13-2
```

For docker-compose, kubernetes, and reverse-proxy templates see the [Install guide](/libra-os/install.md).

***

## Subscribing to release notifications

Three options:

| Channel                    | Cadence                          | Setup                                                                                     |
| -------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| GitHub Releases watch      | Every tag                        | Watch [`libraos/sdk`](https://github.com/libraos/sdk) → Watch → Custom → Releases         |
| `:latest` Docker tag pulls | Every stable release (skips RCs) | `docker pull ghcr.io/libraos/libraos:latest` in your deploy automation                    |
| RSS feed                   | Every release                    | Append `.atom` to the GitHub releases URL: `https://github.com/libraos/sdk/releases.atom` |

For partner-impacting changes (API additions, breaking changes, security fixes) MegaNova also posts to the partner Slack — ask your account contact for an invite.

***

## Next steps

* [**Install guide**](/libra-os/install.md) — first-time setup with the latest stable image
* [**Anthropic SDK Quickstart**](/libra-os/anthropic-sdk-quickstart.md) — point your existing Anthropic-SDK code at the upgraded gateway
* [**Admin Guide**](/libra-os/admin-guide.md) — operational reference for the new tier-routing UI and agent configuration