# KruxOS

> The operating system for AI agents. Typed capabilities, deterministic policy, kernel sandbox.

KruxOS is a purpose-built OS for AI agents. Every OS action is a typed, documented capability with a policy gate. Humans supervise from a web dashboard. Agents connect via MCP WebSocket (port 7700) with an agent API key.

## Agent start here

- [Agent guide](https://kruxos.com/agents/): How AI agents should use KruxOS
- [First-time setup](https://kruxos.com/agents/setup/): Install, first-boot wizard, token provisioning
- [Capabilities](https://kruxos.com/agents/capabilities/): 89 typed APIs across 13 categories
- [Operator guide](https://kruxos.com/agents/operator/): Dashboard, CLI, policy, and settings
- [Auth](https://kruxos.com/auth.md): Agent authentication and token provisioning

## Discovery endpoints

- [API catalog](https://kruxos.com/.well-known/api-catalog): RFC 9727 linkset
- [MCP server card](https://kruxos.com/.well-known/mcp/server-card.json): SEP-1649
- [Agent skills](https://kruxos.com/.well-known/agent-skills/index.json): Skill discovery index
- [OAuth metadata](https://kruxos.com/.well-known/oauth-authorization-server): Token provisioning
- [Protected resource](https://kruxos.com/.well-known/oauth-protected-resource): Bearer auth model

## Ports (per KruxOS instance)

| Port | Service |
|------|---------|
| 7800 | Web dashboard (HTTPS) — human supervision, approvals, policy editor |
| 7700 | MCP / Agent Gateway — WebSocket; agent API key (64-char hex) required |
| 7701 | Supervision WebSocket — `krx_user_*` bearer or operator session |
| 7702 | Trigger-wake (UDP) — loopback only |
| 7703 | User API — loopback HTTP; `krx_user_*` bearer for CLI/automation |

## Install paths

| Path | Best for | Code Sessions |
|------|----------|---------------|
| Docker | Evaluation (~30s) | No |
| VM image | KVM, VirtualBox, VMware, Vagrant | Yes |
| Bare metal | Dedicated hardware, air-gapped | Yes |

Full guides: https://kruxos.com/agents/setup/

## Quick install (Docker)

Docker (evaluation, ~30s):

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

Then open https://localhost:7800 and complete the 8-step first-boot wizard.

## Policy tiers

Every capability call is evaluated against YAML policy:

- `autonomous` — execute immediately
- `notify` — execute, log, notify operator
- `approval_required` — queue for human approval on dashboard
- `blocked` — deny with structured error

## Capability categories (13)

filesystem, process, network, git, scheduler, system, agent, state, comms, secrets, email, slack, alerts

## Documentation

- [Docs home](https://docs.kruxos.com/)
- [Quickstart](https://docs.kruxos.com/quickstart/install/)
- [Developer guide](https://docs.kruxos.com/developers/)
- [Capability reference](https://docs.kruxos.com/developers/capabilities/)
- [MCP integration](https://docs.kruxos.com/developers/mcp/)
- [Policy reference](https://docs.kruxos.com/policies/)
- [Security whitepaper](https://docs.kruxos.com/security/whitepaper/)

## Product pages

- [Home](https://kruxos.com/)
- [Downloads](https://kruxos.com/downloads/)
- [Security](https://kruxos.com/security/)
- [Pricing](https://kruxos.com/pricing/)
- [Efficiency](https://kruxos.com/efficiency/)

## Contact

- Security: security@altvale.com
- Sales: sales@altvale.com
- Discord: https://discord.gg/VXvQKNv6Jn
- GitHub: https://github.com/altvale/kruxos