khy-os 0.1.15

Khy OS — AI platform operating system with an extensible default app runtime

Khy OS

Khy OS is an AI platform CLI and runtime. The default built-in app is khyquant.

Positioning

• khy is the primary Khy OS command (platform shell + app runtime).
• khyquant is the default upper-layer app/plugin compatibility command.
• AI lite mode is explicit: use khy ai ... (or khy --lite ...).
• In the KHY-OS vision, AI is a local super-admin, a remote SSH environment operator, and a mobile-safe context translator (redacted, approval-gated, mobile-first output).

Release Notes (0.1.3)

This release focuses on vision/multimodal adapter compatibility and packaging consistency.

Highlights

• Unified image normalization for gateway adapters:
  • added shared image compatibility layer for base64/data-url/url payloads
  • mapped unified image input to adapter-specific formats (Codex/Claude/Ollama/OpenAI-compatible IDE adapters)
• Removed forced image routing to Claude by default:
  • image requests now keep the selected adapter first
  • gateway fallback remains enabled when a channel actually fails
• Improved local/IDE multimodal behavior:
  • Codex direct mode accepts normalized images
  • Ollama adapter accepts normalized image payloads for multimodal models
  • Trae/Windsurf adapters accept OpenAI-compatible vision message blocks
• Packaging/release consistency:
  • synchronized package version metadata for khy-os==0.1.3
  • fixed release path to avoid mixed/legacy install metadata

Upgrade

python3 -m pip install -U khy-os==0.1.3
khy --version

---

Release Notes (0.1.2)

This release focuses on production stability, multi-adapter robustness, and clearer operator experience.

Highlights

• Improved AI request stability for long-running tasks:
  • task-scale-aware retry/timeout strategy
  • transient error recovery across gateway and tool loop layers
  • safer adapter failover behavior when preferred channels are unstable
• Better context-window safety:
  • dynamic context budget handling
  • stronger compaction path for oversized histories
• Better terminal UX:
  • improved status signaling and de-duplication
  • stronger recovery for interactive input states
• Packaging/version sync:
  • synchronized version bump across Python + Node entry metadata
• release artifacts generated for khy-os==0.1.2

Upgrade

python3 -m pip install -U khy-os==0.1.2
khy --version

Compatibility

• Python: >=3.8
• Node.js: >=18
• OS: Linux / macOS / Windows

Directory Structure

Khy-OS/
├─ khy_quant/                     # Python launcher package (PyPI entrypoint)
│  ├─ cli.py                      # Main Python CLI bridge
│  ├─ _bootstrap.py               # Runtime bootstrap checks/fixes
│  └─ bundled/                    # Bundled runtime assets for pip distribution
│
├─ backend/                       # Node.js core runtime
│  ├─ bin/khyquant.js             # Node CLI entrypoint
│  ├─ server.js                   # API server entrypoint
│  ├─ src/
│  │  ├─ cli/                     # REPL/router/handlers
│  │  ├─ routes/                  # HTTP routes
│  │  ├─ services/                # Gateway, adapters, tools, orchestration
│  │  ├─ tools/                   # Tool implementations
│  │  ├─ models/                  # Data models
│  │  └─ middleware/              # Auth/rate-limit/error middleware
│  └─ tests/                      # Backend tests
│
├─ frontend/                      # Vue frontend
│  ├─ src/
│  │  ├─ components/              # UI components
│  │  ├─ views/                   # Page views
│  │  ├─ services/                # Frontend service layer
│  │  └─ stores/                  # State stores
│  └─ public/                     # Static assets
│
├─ packages/shared/               # Shared JS modules (backend/frontend)
├─ docs/                          # Architecture, guides, verification docs
├─ scripts/                       # Build/install/release scripts
├─ pyproject.toml                 # Python package metadata
└─ backend/package.json           # Node backend metadata

Quick Start

python3 -m pip install -U khy-os
khy --help
khy doctor
khy app list

Development install:

python3 -m pip install -e .

Install Modes

Command	Contents	Size
pip install khy-os	Core CLI + Node backend	~5 MB
pip install khy-os[data]	+ pandas / numpy / akshare	+~50 MB
pip install khy-os[ml]	+ sklearn / xgboost / lightgbm	+~200 MB
pip install khy-os[doc]	+ pdf2docx / pytesseract / Pillow	+~30 MB
pip install khy-os[full]	data + ml + doc	~260 MB

Local LLM Inference (not included in pip)

Local inference binaries (ollama-runner, llama.cpp) are not bundled in the pip package — they are platform-specific and too large (~130 MB). Install separately:

Component	Install	Notes
Ollama (recommended)	curl -fsSL https://ollama.com/install.sh | sh (Linux/macOS) or Download (Windows)	Auto-manages models, easiest setup
llama.cpp	Download from GitHub Releases	Advanced users, manual model management

After installing, verify with:

khy doctor          # checks all available inference backends
khy ai run qwen3.5:4b "hello"   # test local inference

If no local LLM is installed, the AI gateway falls back to remote API providers (Gemini, Groq, OpenRouter, etc.) — core functionality is not affected.

Core Commands

khy app list
khy gateway status
khy linux status
khy server start

Explicit AI Lite Mode

khy ai "summarize this project status"
khy ai -p "only output JSON"
khy ai run qwen3.5:4b "hello"

# compatibility alias (kept for older scripts)
khy run qwen3.5:4b "hello"

OS Build Entry

bash scripts/build-khy-os.sh

Windows (Docker Desktop + PowerShell):

khy iso build --output dist/khy-os.iso
# equivalent source script:
# powershell -ExecutionPolicy Bypass -File scripts/alpine/build-iso-windows.ps1

Component mode:

bash scripts/build-khy-os.sh --component core --component vmware-plan
bash scripts/build-khy-os.sh --component moonbit --strict

WASM App Runtime

khy app register math --runtime wasm --wasm /abs/path/math.wasm --abi numeric-v1 --export add
khy app run math add 1 2

khy app register echo --runtime wasm --wasm /abs/path/echo.wasm --abi string-v2 --export run
khy app exports echo
khy app run echo hello khy os

khy app register score --runtime wasm --wasm /abs/path/score.wasm --abi json-v2 --export run
khy app run score --json '{"symbol":"AAPL","price":192.3,"rsi":63.2}'

# M1 IPC simulation (loopback netd/fsd/wmd)
khy app register weather --runtime wasm --wasm /abs/path/weather.wasm --abi json-v2 --export run --caps ipc,net
khy app ipc weather net http_get --json '{"city":"shanghai"}'

Required Environment

• Python >= 3.8
• Node.js >= 18
• Linux/macOS/Windows

Docker Compose One-Command Startup

Default startup (SQLite mode, no extra manual config required):

docker compose up -d --build
docker compose ps

Verification endpoints:

• Frontend: http://localhost:18080
• Backend health: http://localhost:13000/health
• AI frontend: http://localhost:18090

Optional environment overrides:

cp .env.example .env
# edit .env if you want custom ports or secrets
docker compose up -d --build

Optional PostgreSQL profile:

DB_TYPE=postgres docker compose --profile postgres up -d --build

Pip Distribution Boundary

• Prebuilt ISO/model artifacts and local LLM binaries are intentionally excluded from pip packages.
• You can build ISO locally after installation (khy iso build ...).
• You can download and register models on demand:

khy models pull qwen3.5:4b
khy models list
khy gateway model

See:

• docs/architecture/CORE_ARCHITECTURE.md
• docs/guides/ENV_REQUIREMENTS.md