Agents / Setup

First-time setup.

Three install paths — Docker, VM, or bare metal. Same 8-step wizard. Then connect your MCP client with an agent API key.

Choose your path

PathBest forCode SessionsTime
DockerEvaluation, CI, quick try-outNo~30s
VM imageProduction with hypervisor (KVM, VirtualBox, VMware, Vagrant)Yes~15 min
Bare metalMax performance, air-gapped, dedicated hardwareYes~30 min

Requirements for VM and bare metal: 2 GiB RAM minimum (4 GiB recommended), 20 GiB disk minimum. Architectures: x86_64 and aarch64.

Docker (evaluation)

$ 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. User API (:7703) is loopback-only — no port mapping needed.

Code Sessions not supported in Docker. The dashboard /code page needs cgroup v2 delegation that Docker cannot reliably provide. Use a VM or bare-metal image for code-session workloads. All other features — gateway, dashboard, agents, capabilities, vault, audit — work normally.

CLI inside container: docker exec kruxos kruxos verify

VM image (production)

Download signed artefacts from GitHub Releases or kruxos.com/downloads:

FormatUse with
.qcow2KVM, QEMU, libvirt
.vmdkVirtualBox, VMware
.boxVagrant (libvirt; x86_64 only)
.img.gzRaw image (also used for bare metal — decompress first)

Verify download

$ sha256sum -c SHA256SUMS --ignore-missing $ cosign verify-blob \ --bundle kruxos-x86_64.qcow2.cosign.bundle \ --certificate-identity-regexp '.*' \ --certificate-oidc-issuer-regexp '.*' \ kruxos-x86_64.qcow2

Cosign pubkey: kruxos.com/keys/cosign.pub

Boot with QEMU/KVM

$ curl -LO https://github.com/altvale/kruxos/releases/latest/download/kruxos-x86_64.qcow2 $ qemu-system-x86_64 \ -m 2048 -smp 2 -enable-kvm \ -drive file=kruxos-x86_64.qcow2,format=qcow2,if=virtio \ -netdev user,id=net0,hostfwd=tcp::7800-:7800,hostfwd=tcp::7700-:7700,hostfwd=tcp::7701-:7701 \ -device virtio-net-pci,netdev=net0

Boot with VirtualBox

  1. Create VM: Linux → Other Linux (64-bit), 2048 MB RAM
  2. Attach .vmdk as boot disk
  3. Forward ports 7700, 7701, 7800 to the host
  4. Start VM — console banner shows dashboard URL

Boot with Vagrant (x86_64)

$ vagrant box add kruxos ./kruxos-x86_64.box $ vagrant init kruxos && vagrant up

Default VM firewall accepts TCP 22, 7700, 7701, 7702, 7800. Open https://<vm-ip>:7800.

Verify from VM console: kruxos verify and kruxos sandbox diagnose

Bare metal

Write the raw disk image directly to USB, SSD, or NVMe. Best for dedicated agent infrastructure, maximum sandbox performance, and air-gapped deployments.

Download

$ curl -LO https://github.com/altvale/kruxos/releases/latest/download/kruxos-x86_64.img.gz # aarch64 hosts: kruxos-aarch64.img.gz

Verify

$ sha256sum -c SHA256SUMS --ignore-missing $ cosign verify-blob --bundle kruxos-x86_64.img.gz.cosign.bundle ... kruxos-x86_64.img.gz

Write to disk

$ gunzip kruxos-x86_64.img.gz # Replace /dev/sdX with your target device — this erases the disk $ sudo dd if=kruxos-x86_64.img of=/dev/sdX bs=4M status=progress conv=fsync $ sync
Double-check the target device. dd overwrites the entire disk. Use lsblk or diskutil list to confirm /dev/sdX before writing.

Boot and access

  1. Boot the machine from the USB/SSD (UEFI or legacy BIOS)
  2. Console banner shows the dashboard URL — typically https://<host-ip>:7800
  3. Ensure firewall allows inbound 7700 (agents) and 7800 (operators) on your management network
  4. Keep 7701 (supervision) restricted to localhost or a management VLAN

Verify: kruxos verify from the console (vault passphrase unlocks console root).

Enterprise deployment checklist: docs.kruxos.com/enterprise/deployment-guide

First-boot wizard (all paths)

Open https://<host>:7800 after install. Self-signed HTTPS cert — accept the browser warning on first visit.

  1. Welcome — orientation: secrets, identity, CLIs, policy
  2. Vault passphrase — init/unlock encrypted vault (Docker: same as KRUXOS_VAULT_PASSPHRASE)
  3. Workspace — AdminAgent home dir (default /data/kruxos/users/admin)
  4. AdminAgent (Identity) — name first agent; optional model provider or Skip. Agent API key shown once here.
  5. Licence — paste license JWT or skip (personal use is free)
  6. User token — generate krx_user_* bearer; shown once
  7. Install CLI Tools — optional Claude Code / Codex CLI seed configs
  8. Done — link to main dashboard

Ports

PortServiceExpose?
7800Dashboard (HTTPS)Yes — operator network
7700MCP Gateway (WebSocket)Yes — agent network
7701Supervision WebSocketLocalhost / management VLAN only
7702Trigger-wake (UDP)Loopback only
7703User API (HTTP)Loopback by default

After setup

  1. Save the agent API key from wizard step 4 (or kruxos agent create)
  2. Connect MCP client to ws://<host>:7700/mcp with Authorization: Bearer <64-char-hex>
  3. Store krx_user_* token securely — never commit to source control
  4. Review default policy at /data/kruxos/policies/ (personal-permissive)
  5. Read the capability guide

Full install guide: docs.kruxos.com/quickstart/install