---
title: Agent Guide — KruxOS
description: How AI agents discover, authenticate, and invoke KruxOS typed capabilities via MCP.
---

# Agent Guide

KruxOS is built for you. Connect via MCP on port 7700 with an agent API key, discover 89 typed capabilities, and work within deterministic policy gates.

## Connect via MCP

```
ws://<host>:7700/mcp
```

Auth: `Authorization: Bearer <64-char-hex>` on the WebSocket upgrade, or `?token=<hex>` query param. The key is issued when the operator runs `kruxos agent create` or completes the AdminAgent wizard step.

Call `tools/list` to discover capabilities. Each tool has a typed input schema and returns structured JSON.

## What you can do

- Read and write files (`filesystem.*`)
- Run sandboxed processes (`process.run`)
- Commit to git (`git.commit`, `git.status`)
- Fetch URLs (`network.fetch`)
- Use secrets via vault (`secrets.use` — always policy-gated; raw values never exposed)
- Send email, Slack messages, alerts
- Schedule tasks and communicate with other agents

## Policy tiers

| Tier | What happens |
|------|-------------|
| `autonomous` | Runs immediately |
| `notify` | Runs, operator is notified |
| `approval_required` | Queued — wait for human approval on dashboard |
| `blocked` | Denied; omitted from `tools/list` |

## Authentication by port

| Port | Service | Auth |
|------|---------|------|
| 7700 | MCP / Agent Gateway | Agent API key (64-char hex) |
| 7701 | Supervision WebSocket | `krx_user_*` bearer or operator session |
| 7703 | User API (loopback) | `krx_user_*` bearer |
| 7800 | Dashboard | Operator passphrase (bcrypt) |

## Start here

1. [Setup guide](https://kruxos.com/agents/setup/) — install and first-boot wizard
2. [Capabilities](https://kruxos.com/agents/capabilities/) — full capability reference
3. [Operator guide](https://kruxos.com/agents/operator/) — how your operator supervises you
4. [auth.md](https://kruxos.com/auth.md) — credential provisioning