---
title: First-Time Setup — KruxOS
description: Install KruxOS via Docker, VM, or bare metal. Complete the 8-step wizard and provision agent credentials.
---

# First-Time Setup

Three install paths. Same 8-step wizard. Connect MCP with an agent API key after setup.

## Choose your path

| Path | Best for | Code Sessions | Time |
|------|----------|---------------|------|
| Docker | Evaluation, CI | No | ~30s |
| VM image | KVM, VirtualBox, VMware, Vagrant | Yes | ~5 min |
| Bare metal | Dedicated hardware, air-gapped | Yes | ~10 min |

Requirements (VM / bare metal): 2 GiB RAM min (4 GiB recommended), 20 GiB disk. Architectures: x86_64, aarch64.

## Docker (evaluation)

```bash
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.

**Code Sessions are not supported in Docker** — use VM or bare metal for `/code` page workloads.

## VM image (production)

Download from [GitHub Releases](https://github.com/altvale/kruxos/releases) or [kruxos.com/downloads](https://kruxos.com/downloads/):

| Format | Use with |
|--------|----------|
| `.qcow2` | KVM, QEMU, libvirt |
| `.vmdk` | VirtualBox, VMware |
| `.box` | Vagrant (x86_64) |
| `.img.gz` | Raw (also bare metal) |

### Verify

```bash
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
```

### QEMU/KVM

```bash
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
```

### VirtualBox

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

### Vagrant (x86_64)

```bash
vagrant box add kruxos ./kruxos-x86_64.box
vagrant init kruxos && vagrant up
```

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

Verify: `kruxos verify` and `kruxos sandbox diagnose`

## Bare metal

Write raw image to USB, SSD, or NVMe. Best for dedicated infrastructure and air-gapped deployments.

### Download and decompress

```bash
curl -LO https://github.com/altvale/kruxos/releases/latest/download/kruxos-x86_64.img.gz
gunzip kruxos-x86_64.img.gz
```

### Write to disk

```bash
# Replace /dev/sdX — erases entire disk
sudo dd if=kruxos-x86_64.img of=/dev/sdX bs=4M status=progress conv=fsync
sync
```

Confirm target with `lsblk` before running `dd`.

### Boot

1. Boot from USB/SSD (UEFI or legacy BIOS)
2. Console banner shows `https://<host-ip>:7800`
3. Allow inbound 7700 (agents) and 7800 (operators) on your network
4. Restrict 7701 (supervision) to localhost or management VLAN

Verify from console: `kruxos verify`

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

## First-boot wizard (8 steps)

1. **Welcome** — orientation
2. **Vault passphrase** — init/unlock vault
3. **Workspace** — AdminAgent home (`/data/kruxos/users/admin`)
4. **AdminAgent (Identity)** — agent name + optional model provider; **API key shown once**
5. **Licence** — paste JWT or skip
6. **User token** — `krx_user_*` bearer, shown once
7. **Install CLI Tools** — optional Claude Code / Codex seed configs
8. **Done**

## Ports

| Port | Service | Expose? |
|------|---------|---------|
| 7800 | Dashboard | Operator network |
| 7700 | MCP Gateway | Agent network |
| 7701 | Supervision WS | Localhost / mgmt VLAN |
| 7702 | Trigger-wake (UDP) | Loopback |
| 7703 | User API | Loopback |

## After setup

1. Save agent API key from step 4
2. Connect MCP: `ws://<host>:7700/mcp` with Bearer auth
3. Store `krx_user_*` token securely
4. Review policy at `/data/kruxos/policies/`

## User token {#user-token}

Wizard step 6 or `kruxos user-token create --label <label>`.