zOS

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.

Declare once—run everywhere.

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.

Quick Start

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 | iex

Or plain pip (Python 3.10–3.12):

pip install zolo-os

Then run a demo:

git clone https://github.com/ZoloAi/zOS.git
cd zOS/zDemos/zHello
z zSpark.zhello.zolo

⚠️ PyPI warning: the package is zolo-os. An unrelated public zolo package exists on PyPI and will cause conflicts — don't install it.

📚 New to Zolo?

Start with The zPhilosophy.
It introduces the core concepts of zOS and smoothly leads into the layer-by-layer guides with ready-made demos.

Requirements

• CPython 3.10 – 3.12 (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.

Installation Options

See zInstall Guide for editable install and troubleshooting.

🏗️ Architecture

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)

Subsystems by Layer

🔒 Security & secrets

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.* and certs/*.key|pem|cert gitignored — 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 and WEBSOCKET_ALLOWED_ORIGINS.

Alpha note: WebSocket origin/CSRF validation is enabled together with WEBSOCKET_REQUIRE_AUTH (per-feature toggles land before v2.0), and the shared WS token uses a direct compare. Hardening continues through the alpha.

Uninstall & cleanup

Run this command in your terminal:

zolo uninstall

This launches an interactive menu where you can choose:

1. Framework Only (default) - Removes the package, keeps your data and optional dependencies
2. Clean Uninstall - Removes package AND all user data (configs, databases, cache)
3. 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.

More details →

License

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.

Documentation

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

Next: The zPhilosophy →