Alpha — v1.6 zOS is stable and actively used in production internally. The API is functional and the architecture is settled, but rough edges remain. The
Documentation/guides are technically accurate against the core design; some details may lag behind the latest source. Live, up-to-date docs are coming with the official alpha release via zCloud (zolo.media). Expect breaking changes before v2.0.Every release is gated on the full demo test matrix passing on macOS, Linux, and Windows — arm64 and x86_64.
zOS is not just a Command Line Interface, but a Context Layer Interface—a declarative cross-platform Python framework where context flows through layers to determine how your application manifests.
Write once, adapt to any context: user role, deployment environment, device, or runtime mode (Terminal or Web). zOS handles the heavy lifting, turning ideas into working tools faster.
One-line install (isolated venv at ~/.zolo, CLI on your PATH):
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ZoloAi/zOS/main/install.sh | bash# Windows (PowerShell)
irm https://raw.githubusercontent.com/ZoloAi/zOS/main/install.ps1 | iexOr plain pip (Python 3.10–3.13):
pip install zolo-os
⚠️ The package name iszolo-os— exactly that.pip install zolosucceeds but installs an unrelated squatted package that has nothing to do with zOS. There is nozolo-desktoporzos-desktopeither — the desktop/native-window mode is an extra of the same package:pip install "zolo-os[webview]".
Then run a demo:
git clone https://github.com/ZoloAi/zOS.git
cd zOS/zDemos/zHello
z zSpark.zhello.zoloStart with The zPhilosophy.
It introduces the core concepts of zOS and smoothly leads into the layer-by-layer guides with ready-made demos.
- CPython 3.10 – 3.13 (the range the zGuard trust binaries ship for)
- macOS / Linux / Windows, arm64 or x86_64
Need help installing requirements on Windows or macOS?
See zInstall Guide for detailed instructions.
| Variant | Use Case | Install Command |
|---|---|---|
| Basic | CSV + SQLite backends | pip install zolo-os |
| PostgreSQL | + PostgreSQL backend | pip install "zolo-os[postgresql]" |
| Webview | + native desktop window mode (zDesktop) | pip install "zolo-os[webview]" |
| Monitoring | + Prometheus metrics | pip install "zolo-os[monitoring]" |
| Full | everything above | pip install "zolo-os[all]" |
See zInstall Guide for editable install and troubleshooting.
zOS v1.5+ (Context Layer Interface) follows a 5-layer architecture inspired by "Linux From Scratch"—each subsystem stands alone, tested independently, then composed into higher abstractions.
Layer 0: /zSys/ — Pre-boot utilities: formatting, errors, install, logging, CLI routing
Layer 1: /L1_Foundation/ — zConfig (config hierarchy + secrets) + zComm (HTTP, WebSocket, services)
Layer 2: /L2_Handling/ — Display, Auth, Dispatch, Navigation, Parser, Loader (+ plugins), Func, Dialog, Open
Layer 3: /L3_Abstraction/ — zWizard (workflows), zData, zBifrost (WS bridge), zShell (REPL)
Layer 4: /L4_Orchestration/ — zWalker (declarative UI orchestrator) + zServer (HTTP/WSGI server)
| Subsystem | Purpose |
|---|---|
| Layer 1 — /L1_Foundation/ | |
| zConfig | Self-aware config layer — machine → environment → session hierarchy with secrets + logging |
| zComm | Communication hub — HTTP client, service orchestration (PostgreSQL, Redis), network utilities |
| Layer 2 — /L2_Handling/ | |
| zDisplay | Render everywhere — 30+ events (tables, forms, widgets) adapt to Terminal or GUI automatically |
| zAuth | Three-tier auth system — bcrypt + RBAC + git-like identity, manage platform + multi-app users simultaneously |
| zDispatch | Universal command router — simple modifiers (^~*!) shape behavior, routes to 7+ subsystems seamlessly |
| zNavigation | Unified navigation — menus + breadcrumbs + state + inter-file links, all RBAC-aware |
| zParser | Declarative paths & parsing — workspace-relative + user dirs + plugin discovery, 21+ unified methods |
| zLoader | Intelligent file loader — 4-tier cache system (System + Pinned + Schema + Plugin) with mtime tracking |
| zFunc | Dynamic Python executor — cross-language (using zBifrost) + internal Python, auto-injection removes boilerplate |
| zDialog | Declarative form engine — define once, auto-validate, render everywhere (Terminal or GUI) |
| zOpen | Universal opener — cross-OS routing (URLs, files, zPaths) for your tools (session-aware browser + IDE preferences) |
| Layer 3 — /L3_Abstraction/ | |
| REMOVED v1.7.0 — Plugin management migrated to zLoader (Layer 1) - see migration guide | |
| zWizard | Multi-step orchestrator — sequential execution + zHat result passing, enabling workflows and navigation |
| zData | Database abstraction — backend-agnostic declarations (SQLite ↔ PostgreSQL ↔ CSV), and auto migration |
| zBifrost | WebSocket bridge — real-time bidirectional communication (server + JavaScript client), enables Terminal → Web GUI transformation |
| zShell | Interactive command center — 18+ commands + wizard canvas, persistent history, direct access to all subsystems |
| Layer 4 — /L4_Orchestration/ | |
| zWalker | Declarative UI orchestrator — menus + breadcrumb navigation, coordinates the lower-layer subsystems, Terminal and GUI |
| zServer | HTTP/WSGI server — serves HTML/CSS/JS + declarative routing, dev mode (lightweight) and production mode (Gunicorn), pairs with zBifrost |
| zRaven | Automated test subsystem — drives zWalker + zServer + zBifrost end-to-end; zSpark-activated, off by default |
| L4 overview → |
zOS treats environment files like dotenv: zEnv.base.zolo and zEnv.<env>.zolo
are parsed and injected into os.environ at boot — they are never served over
HTTP. The built-in zServer SecurityChecker returns 403 for:
- env/config/manifest files (
/zEnv.*,/zConfig.*,/zSpark.*,/certs/, …) - any hidden path segment (
/.git/,/.env, …) — even nested under a mount - source/secret file types served as assets (
.py,.zolo,.key,.pem,.db, …)
So a /plugins/ mount serves your client .js, but never the server-side .py.
Production checklist
- Keep
zEnv.*andcerts/*.key|pem|certgitignored — never commit real secrets. - Inject prod secrets via the platform (IAM role / secrets manager), not files.
- Set TLS certs in
zEnv.production→ HTTPS/WSS auto-enable (TLS 1.2+). - Set the public
WEBSOCKET_HOST/port andWEBSOCKET_ALLOWED_ORIGINS.
Alpha note: WebSocket origin/CSRF validation is enabled together with
WEBSOCKET_REQUIRE_AUTH(per-feature toggles land before v2.0) — set it in production. Token verification is constant-time (hmac.compare_digest).
Run this command in your terminal:
zolo uninstallThis launches an interactive menu where you can choose:
- Framework Only (default) - Removes the package, keeps your data and optional dependencies
- Clean Uninstall - Removes package AND all user data (configs, databases, cache)
- Dependencies Only - Removes optional dependencies (pandas, psycopg2) but keeps zOS
Each option shows you exactly what will be removed and asks for confirmation before proceeding.
MIT License with Ethical Use Clause
Copyright (c) 2024 Gal Nachshon
Trademarks: "Zolo" and "zOS" (Context Layer Interface) are trademarks of Gal Nachshon.
See LICENSE for details.
The guides below are technically accurate against the core architecture, but some details may be slightly behind the current source. Live docs with full examples will ship with the official alpha at zolo.media.
- zPhilosophy - Core concepts and design principles
- Installation Guide - Setup instructions
- AI Agent Guide - Reference for AI coding assistants
- Subsystem Guides - Guides for all 20+ subsystems