Overview
zOS is an AI-native operating system for people and organizations: AI that knows everything you teach it and never shares it in the wrong room. The homepage tells that story; this page is the architecture — the layers of the stack, what each one does, and where every component sits. If you read nothing else, read this page — it defines the vocabulary every reference uses.
Three terms carry most of the weight. A context is one room of your life or business — work, personal, each client — declared as a plain config file. The canon is the assembled set of values, priorities, and rules your AI loads at the start of every session. The firewall is each context's declared list of things that must never leave that room, checked on every call.
The architecture
Three working layers — experience on top, trust in the middle, the brain underneath — with five supporting libraries around them and your own model providers and storage at the bottom. Every model call enters at the top and is governed on the way down and again on the way back up.
The division of labor is deliberate. zos‑core defines what your AI knows, obeys, and remembers; zos‑gateway is the checkpoint that enforces it on every call. The core is source-visible so the guardrails can be verified, not merely promised. The gateway is the product. Full references: zos-core library API · zos-gateway REST API.
zos-gateway — the trust layer
A self-hosted server that sits between any AI application and the model providers. It speaks the same API your tools already use, so adopting it is pointing them at a different address — and from that moment, every call is governed.
- Per-call enforcement. Each request resolves its context, gets firewall-scanned before the model sees it and again before the answer reaches the app — including mid-stream, where a violating streamed response is cut before the offending words leave the building.
- Budgets. Daily token budgets per context; exceeded means a clean refusal, not a surprise invoice.
- Your keys, your data plane. Bring-your-own API keys; the gateway runs in your infrastructure; prompts and memory never transit anyone else's servers.
- Audit, always. An append-only record of every call — context, model, token counts, firewall verdicts, latency — that never logs message content or keys.
- Deployment. One container; Docker Compose quickstart; works standalone or with zos-core installed for the full brain.
Status: working code · 40 tests · CI green · BUSL-1.1 · repository private until public launch. Full reference →
zos-core — the brain engine
Everything about how a person's (or an organization's) AI is configured lives here, as plain files you own.
- Contexts as config. Each context is one file declaring its register (voice and tone), default role, allowed tools, and firewall — the list of things that must never leave that room. Hard-isolated contexts block; everything else warns.
- Canon assembly. Your values, priorities, and rules are markdown files assembled in strict hierarchy order into the canon the AI loads at the start of every session — with a byte budget, and a degraded mode that announces itself when something is missing instead of silently running lawless.
- Memory with discipline. One fact per file, typed and write-gated; per-context indexes plus a shared bus that respects isolation (a client context never receives another's facts); byte budgets that gracefully archive instead of growing forever.
- Model routing. Classifies each task's shape and picks the cheapest model tier that can actually do it — suggestion-only by default, with explicit opt-in for active routing and a kill switch.
- Setup wizard.
zos initseeds a new brain on a neutral safety floor — your own values and rules on top of non-negotiable do-no-harm ground rules. Onboarding is two-sided: a personal wizard and an organization wizard (zos init --org), and individuals join an org withzos join, inheriting the org canon by reference — org → team → personal.
Status: working code · 132 tests · CI green · BUSL-1.1 · repository private until public launch. Full reference →
The component family
Two products carry the promise; five focused libraries carry the operations around it. Each library is a standalone Python package — stdlib-only at runtime (zos-evals adds PyYAML) — usable with or without the rest of zOS.
- zos-core — the brain engine: contexts, firewall, canon, lints, attestation, memory, routing, and the
zosCLI. - zos-gateway — the trust layer: the self-hosted checkpoint every model call passes through.
- zos-evals — the eval harness: did a configuration change actually make the system better? Position-debiased judging, no false zeros.
- zos-loops — the loop engine for unattended operation: singleton locks, dual-axis heartbeats, per-step isolation, backoff, kill-switch.
- zos-telemetry — the measurement layer: corrections per session, cost, and cross-system comparison — content-free by construction.
- zos-agent-mq — the brokerless file-backed message queue agents on one machine use to talk to each other.
- zos-voice — privacy-first voice-note ingestion: local-only transcription, never opens a network connection.
Licensing
Every zOS component — the two products and the five libraries — is source-visible under the Business Source License 1.1. BUSL-1.1 means: free for personal, non-commercial production use; production use by or for an organization requires a commercial license; and each version automatically becomes Apache 2.0 four years after its release. Selected components may move to Apache earlier as the platform matures.
What is deliberately not built yet
The managed control plane (org, seat, and context governance dashboards), the compliance rule packs (healthcare first), and the hosted tier are roadmap, not code. These pages describe only what exists and passes tests today — the same honesty rule the rest of this site follows.