Skip to content

KruxOS v0.0.1 — first release

Released: 2026-05-14 Status: Early beta — not for production use.

KruxOS is a purpose-built operating system for AI agents — designed from the agent's perspective, not adapted from a human OS. Every OS capability is exposed as a typed, documented API; agents discover and invoke through a structured pipeline rather than navigating shell or GUIs. Every call is mediated by a deterministic policy engine — no LLM in the hot path — and routed through the operator approval queue when policy says so. Humans interact through a web dashboard built for oversight; agents through the typed tool surface.

v0.0.1 ships as a self-hosted appliance: bootable VM image (x86_64 + aarch64), Docker image, dashboard, CLI, and an in-appliance Python SDK.

Highlights

  • Deterministic policy engine. Four-tier permission model (autonomous / notify / approval_required / blocked), evaluated with no LLM in the loop. Hot-reloadable YAML; per-agent overrides.
  • One approval surface. Claude Code, OpenAI Codex, and any cli-config'd CLI route every gated tool call through the KruxOS approval queue. No in-CLI prompts; no governance bypass via the CLI's native shell tool.
  • 89 typed capabilities across 13 categories — filesystem, process, network, git, scheduler, system, agent, state, comms, secrets, email, Slack, alerts. MCP-native with JSON-RPC fallback.
  • Per-agent sandbox. Linux user/network namespaces, cgroup v2 limits, seccomp BPF allowlist, nftables defense-in-depth — applied per capability call via a forked child.
  • Bootable appliance image. Distributed as .img.gz, .qcow2, .vmdk, and Vagrant .box for x86_64 and aarch64. All artefacts cosign-signed (long-term keypair; public key at kruxos.com/keys/cosign.pub) for offline verification.
  • First-boot dashboard wizard at http://<host>:7800 walks new operators through vault passphrase, AdminAgent, license activation, User token, and CLI install.

What's in the box

  • Gateway — MCP-native on TCP 7700 with JSON-RPC fallback; supervision WebSocket on 7701 (30 s ping / 10 s timeout keepalive, 16 MiB default max message size); UDP trigger-wake on 127.0.0.1:7702; bearer-auth User API on 7703 (distinct principal from token-auth agents); dashboard on 7800 (HTTPS by default, auto-generated self-signed cert). Bridges ship for Claude Code (stdio) and OpenAI Codex. KRUXOS_ENV=production enables fail-closed startup.
  • Policy engine — deterministic, hot-reloadable YAML at /data/kruxos/policies/{system,org,agents/<name>}.yaml. Visual + YAML editor on the dashboard; per-agent overrides; User Rules surface on the Identities page. Wizard creates a personal-permissive AdminAgent policy at first boot.
  • Approval queue — persistent, surfaced on the dashboard with Pending / Approved / Rejected / Timed Out tabs. Default 24-hour hold for User MCP calls (configurable). 30-second WebSocket keepalive during long holds. Timed-out approvals cannot be approved retroactively (HTTP 409 with status discriminator). Audit log preserves the original approval_required tier through the decision chain.
  • Capabilities — 89 typed capabilities across 13 categories: filesystem (12), process (5), network (4), git (8), scheduler (4), system (4), agent (4), state (24), comms (4), secrets (3), email (7), Slack (7), alerts (3). MCP tools/list and JSON-RPC capabilities.list annotate each with its policy tier; blocked capabilities are omitted entirely.
  • Sandbox — per-agent Linux user + network namespaces, cgroup v2 limits, seccomp BPF allowlist (no libseccomp dependency), nftables defense-in-depth. Default limits: 512 MiB memory, 50 % CPU, 100 PIDs, 50 MiB/s read, 25 MiB/s write. Per-call fork model applies the full sandbox to capability handlers; stateless capabilities (system.time / info / health, agent.whoami) execute in-process. kruxos sandbox diagnose [--json] reports per-primitive status.
  • Secrets vault — AES-256-GCM SQLite at /data/kruxos/vault.db. Use-not-read contract: capability handlers reference vault entries by id, never the raw secret. KRUXOS_VAULT_PASSPHRASE unlocks at startup; bcrypt hash persisted at ${data_dir}/vault_passphrase_hash for dashboard login. OAuth tokens (Gmail, Codex, Slack) stored with auto-refresh.
  • Audit log — length-prefixed CBOR framing, hash-chained for tamper evidence; Principal-aware actor field ({type:"user"} / {type:"agent",name:...}); path_escape events on symlink-escape attempts; delegation metadata envelope on comms rows; 10,000-entry bounded ring-buffer + 30-second retry on disk-full (no audit loss to silent crash); daily rotation at 03:00 UTC, 90-day default retention.
  • Agent runtime — autonomous five-field cron schedules, one-shot delays, manual trigger via kruxos agent run or loopback UDP wake. Three state scopes (session / persistent / shared); per-agent Agent.md identity injected into every system prompt; per-agent host mounts under /mnt/<label> with path-escape detection; topic-based inter-agent comms broker (comms-triggered wakes near-instant); per-principal soft-delete trash with restore (168 h User / 24 h Agent default retention); OpenClaw compatibility bridge.
  • Model providers — Anthropic, OpenAI (+ DeepSeek / Grok / Mistral / Groq / GLM via base_url), OpenAI Codex (subscription / device-code OAuth), OpenRouter (200+ models), Google Gemini, Local (Ollama / vLLM / LM Studio / llama.cpp). Provider-native prompt caching (Anthropic 1-hour cache TTL via extended-cache-ttl-2025-04-11 header). Two-tier context compaction with coder / researcher / email / devops / general templates. Configurable thinking-effort levels (none / low / medium / high / max). Per-agent model assignment
  • per-request override.
  • Dashboard — real-time supervision view; approval queue; audit viewer with Principal-aware filter; multi-model chat with persisted sessions, knowledge panel, inline approval flow; Agents page (templates: Coder / Researcher / DevOps / Email / General, with model overrides, Agent.md identity, per-agent policy, host mounts); visual + YAML policy editor; Settings (one card per provider, connection tests); Identities page (User token CRUD, one-time raw-token reveal); Integrations page (Claude Code / Codex install, regenerate ~/.claude/CLAUDE.md
  • ~/.codex/AGENTS.md briefings); Code Sessions (/code, xterm.js terminals through the gateway sandbox); first-boot Wizard.
  • Host-CLI integrations — mcp-bridge at /opt/kruxos/bin/mcp-bridge (stdio↔WebSocket, token never in argv, structured exit codes); cli-hook at /opt/kruxos/bin/cli-hook (forwards Claude Code / Codex pre-tool events with native-tool→capability mapping — cat → filesystem.read, grep → filesystem.search_content, curl → network.http_request); kruxos cli-config generate [--write] emits seed configs. Codex MCP hardening: tool_timeout_sec=86400, required=true, native shell and unified_exec disabled at user-config and requirements layers.
  • Code sessions — kruxos code list / kill <id> / attach <id> against the loopback User API. Concurrent-session cap default 4 (5th spawn returns HTTP 429); per-session cgroup v2 memory cap default 2 GiB; 4-hour idle timeout. Workdir validation (operator home + registered mounts only). Three-hop end-to-end backpressure (64 KiB / 32 KiB watermarks). Origin pinning on the dashboard ws-proxy.
  • CLI — single kruxos binary covering activate, agent, audit, cli-config, code, migrate, model, mount, pack, sandbox diagnose, state backup / restore / backups, trash list / cleanup, user-token, vault, verify, version, status, watch. Shell completions for bash / zsh / fish; on-demand man pages via kruxos man <command>.
  • Distribution artefacts — kruxos-{x86_64,aarch64}.img.gz, .qcow2 (libvirt / KVM / QEMU), .vmdk (VMware / VirtualBox), Vagrant .box (libvirt; x86_64 only). SHA256SUMS plus a per-artefact .sig file (long-term cosign keypair; public key at https://kruxos.com/keys/cosign.pub) for offline verification. Default firewall accepts TCP 7700 / 7701 / 7702 / 7800 (no SSH daemon ships in the appliance). Daily state backups (02:00 UTC) and audit-log rotation (03:00 UTC, 90-day retention) via systemd timers.
  • Docker image — altvale/kruxos:v0.0.1 and :latest on Docker Hub. Buildroot-based rootfs (~99 MiB compressed, ~300 MiB on disk). Run with docker run --privileged -e KRUXOS_VAULT_PASSPHRASE=<pw> -p 7800:7800 -p 7700:7700 -p 7701:7701 altvale/kruxos:latest. Same first-boot wizard. Code Sessions feature unsupported on this image — see Known limitations below.
  • Python SDK — bundled in-appliance at /opt/kruxos/sdk/python/, importable from interactive shells via /etc/profile.d/kruxos-sdk.sh. Async client over the supervision WebSocket; typed exception classes; per-request model override via Trigger and ChatSendRequest; bundled connectors for Anthropic, OpenAI, Gemini, and Local providers.
  • Capability Pack SDK — local-path install via kruxos pack install <local-path> works on the v0.0.1 appliance. Community registry, pack-sdk CLI distribution, GitHub-based publishing flow, and seed packs land in v0.0.2.
  • Licensing — Ed25519-signed JWT verifier. Activate via kruxos activate <key> / --file <path> / - (stdin), or via the dashboard wizard License step. License JWT at /data/kruxos/license.jwt (mode 0600). Visit kruxos.com for license details.

Security

  • KruxOS is the single approval and policy enforcement surface.
  • Mass-destruction commands blocked unconditionally (rm -rf /etc | /usr | /opt | …, dd of=/dev/sd*, mkfs.* /dev/..., redirects to raw block devices).
  • Per-principal soft-delete trash with retention.
  • TLS on the dashboard by default; ws-proxy Origin pinning rejects mismatched / null origins on code-session upgrades.
  • CVE-2026-31431 (algif_aead Copy Fail) is structurally unreachable (kernel built without CRYPTO_USER_API_* / ALGIF_AEAD).
  • Release artefacts signed with a long-term cosign keypair (no per-release OAuth identity in public logs). Per-artefact .sig file; public key at https://kruxos.com/keys/cosign.pub. See SECURITY.md for the full verification flow.
  • /.well-known/security.txt published per RFC 9116 (security@altvale.com).
  • Console root login is bound to the vault passphrase — same secret unlocks the vault, the dashboard login, and console root.

Reporting issues

  • Security disclosures: /.well-known/security.txt or security@altvale.com.
  • Bug reports + feature requests: GitHub Issues on this repository.

Community

Join the KruxOS Discord for community support, discussion, and idea brainstorming: discord.gg/VXvQKNv6Jn.