Skip to content

Getting Started with KruxOS

This page walks you from zero to a working KruxOS instance with a connected AI agent. Total time: under 15 minutes.

Step 1: Run KruxOS (5 minutes)

docker run -d --name kruxos --privileged \
  -e KRUXOS_VAULT_PASSPHRASE='choose-a-strong-passphrase' \
  -p 7800:7800 \
  -p 7700:7700 \
  -p 7701:7701 \
  -v kruxos-data:/data/kruxos \
  altvale/kruxos:latest

Open https://localhost:7800 and finish the first-boot wizard (vault passphrase, AdminAgent, license, User token, CLI install).

Verify it's running:

docker exec kruxos kruxos verify

Full Docker reference

See Install KruxOS for port details, sandbox notes, and troubleshooting.

Code Sessions not supported on Docker in v0.0.1

Code Sessions (/code page + kruxos code … subcommands) need cgroup v2 delegation that isn't reliable through Docker. All other features work normally. Docker-side fix ships in v0.0.2.

Download the artefact for your hypervisor from https://github.com/altvale/kruxos/releases:

  • kruxos-x86_64.img.gz / kruxos-aarch64.img.gz — raw disk image
  • kruxos-x86_64.qcow2 — libvirt / KVM / QEMU
  • kruxos-x86_64.vmdk — VMware / VirtualBox
  • kruxos-x86_64.box — Vagrant (libvirt; x86_64 only)

All artefacts are cosign-signed; per-artefact .cosign.bundle files include the Fulcio cert + Rekor inclusion proof for offline verification.

See Install KruxOS for the boot walkthrough.

Step 2: Connect your AI model (5 minutes)

On the appliance:

kruxos cli-config generate --write

Writes ~/.claude/settings.json referencing the bundled /opt/kruxos/bin/mcp-bridge, with the agent token pulled from the vault. Claude Code's native shell tool is disabled at the user-config and requirements layers so every tool call routes through the KruxOS approval queue.

Restart Claude Code. Ask: "What tools do you have from KruxOS?" — Claude should list the capabilities visible to your policy tier.

Other clients

Python SDK (programmatic access)

The Python SDK ships bundled inside the appliance at /opt/kruxos/sdk/python/ (auto-importable via /etc/profile.d/kruxos-sdk.sh). The external pip install kruxos distribution to PyPI ships in v0.0.3.

import asyncio
from kruxos import KruxOS

async def main():
    os = await KruxOS.connect_async(
        endpoint="ws://localhost:7700",
        agent_name="default-agent",
        api_key="<64-char hex>",
    )
    try:
        result = await os.call_async("system.time")
        print(f"Server time: {result.data['utc']}")

        caps = await os.capabilities.list_async()
        print(f"Available: {len(caps)} capabilities")
    finally:
        await os.close_async()

asyncio.run(main())

Step 3: Explore (5 minutes)

Web Dashboard

Open https://localhost:7800 in your browser (HTTPS-by-default with an auto-generated self-signed cert — accept the prompt on first visit).

Page What it shows
Home System health, active agents, recent activity, pending approvals
Supervision Real-time stream of every capability invocation (TCP 7701 WS)
Agents Templates (Coder / Researcher / DevOps / Email / General), model overrides, host mounts
Approvals Pending / Approved / Rejected / Timed Out tabs; default 24-hour hold for User MCP calls
Audit Searchable hash-chained audit log with Principal-aware filtering
Chat Multi-model chat with persisted sessions, knowledge panel, inline approvals
Code Sessions (/code) xterm.js terminals through the sandbox — VM image only in v0.0.1
Identities User token CRUD with one-time raw-token reveal
Integrations Claude Code / Codex install, regenerate seed configs
Policies Visual + YAML editor, per-agent overrides
Settings One card per model provider (Anthropic, OpenAI, Codex, OpenRouter, Gemini, Local, DeepSeek, Grok, Mistral, Groq, GLM)

CLI

# Docker: prefix with `docker exec kruxos`
kruxos status                  # System overview
kruxos agent list              # Connected agents
kruxos audit query --last 1h   # Recent audit events
kruxos --help                  # Full command reference

To enumerate capabilities, query MCP tools/list or JSON-RPC capabilities.list over the Gateway — each entry is annotated with its policy tier; blocked capabilities are omitted.

Try these prompts with Claude

Once connected, try these in a conversation:

  • "What time is it on the server?" — calls system.time
  • "List files in the workspace" — calls filesystem.list
  • "Create a file called hello.txt with 'Hello World'" — calls filesystem.write (may require approval)
  • "What agent am I?" — calls agent.whoami
  • "Show me system info" — calls system.info

What to do next