Documentation.

What is Klawty?

Klawty is an open-source AI agent operating system. It's a security-hardened fork of OpenClaw (302K+ stars, MIT) with custom security modules built by dcode technologies. You get a complete runtime for autonomous AI agents with deny-by-default security, PII detection, credential monitoring, and runtime integrity verification.

What you get (free version)

1 agent (Atlas) with read-only tools, the full OpenClaw CLI (40+ commands), 20+ communication channels, 52 community skills, Docker deployment, and Klawty security modules (policy engine, exec sandbox, PII detection, credential monitor, integrity checks, privacy router).

Requirements

Node.js 22+, a machine that stays on (Mac, Linux server, VPS, or Docker), and an OpenRouter API key for LLM access. Docker is recommended for Qdrant vector memory and the exec sandbox but is not required.

Install

From source

Two layers

Klawty combines two systems: (1) OpenClaw — CLI, 20+ channels, plugin SDK, gateway, memory embeddings, native apps, 52 skills. (2) Klawty security layer — deny-by-default policy engine (klawty-policy.yaml), Docker exec sandbox, PII detection, credential monitoring, SHA-256 runtime integrity, privacy router, auto-update with rollback.

Gateway

The gateway is the central process. It manages WebSocket connections, routes messages between channels and agents, handles authentication, and serves the Control UI. Default port: 2508.

klawty gateway --port 2508

Agent model

Agents are defined in Markdown files (AGENT.md) with YAML frontmatter. Each agent has a model, heartbeat cycle, tool permissions, skills, and a discovery prompt. Adding a new agent = creating one AGENT.md file. No code required.

Memory system

File-based by default: MEMORY.md stores persistent knowledge (50 lines max in free version). Session logs are JSONL files per day. Premium adds Qdrant vector memory for semantic search across all past knowledge.

Workspace structure

workspace/
├── klawty.json           # main config
├── SOUL.md               # system personality
├── IDENTITY.md           # agent identity
├── AGENTS.md             # roster
├── TOOLS.md              # tool reference
├── MEMORY.md             # persistent knowledge
├── HEARTBEAT.md          # periodic check schedule
├── USER.md               # operator profile
├── agents/main/AGENT.md  # agent config
└── skills/               # domain skills

klawty.json

Main configuration file. Defines agent defaults (model, timeout, tool permissions), channel settings, and memory config. Supports JSON5 (comments allowed). Located at ~/.klawty/klawty.json (global) or workspace/klawty.json (per-workspace).

{
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" },
      "tools": { "allow": ["file_read", "web_search"], "deny": ["exec"] }
    },
    "list": [{ "name": "atlas", "role": "orchestrator" }]
  },
  "memory": { "maxMemoryLines": 50 },
  "channels": { "default": "terminal" }
}

SOUL.md

Defines the agent's personality — rules, boundaries, operating principles. Edit it in plain Markdown. The agent reads this at the start of every session.

AGENT.md

Per-agent configuration via YAML frontmatter: model, cycle interval (minutes), tools (allow/deny lists), skills, channel, and discovery prompt. The body is free-form instructions for the agent.

---
name: atlas
model:
  primary: "anthropic/claude-sonnet-4-6"
cycle: 30
tools:
  allow: [file_read, web_search, web_fetch, recall_memory, store_memory]
  deny: [exec, file_write]
channel: terminal
---

You are Atlas, the main agent.

klawty-policy.yaml

Security policy file (deny-by-default). Controls which network endpoints agents can reach, which filesystem paths they can write, which shell commands they can run, and resource limits. Edit to allow specific APIs, domains, or tools.

Environment variables

# .env — copy from .env.example
OPENROUTER_API_KEY=sk-or-v1-...
QDRANT_URL=http://localhost:6333
# DISCORD_BOT_TOKEN=
# SLACK_BOT_TOKEN=
# TELEGRAM_BOT_TOKEN=
LOG_LEVEL=info

OpenRouter (recommended)

We recommend OpenRouter as your LLM provider. One API key gives access to 200+ models — Claude, GPT-4, Gemini, DeepSeek, Mistral, Llama, and more. Sign up at openrouter.ai, get your key, add it to .env. That's it.

Core commands

klawty run               # start all agents
klawty status            # health, tasks, costs
klawty stop              # graceful shutdown
klawty tui               # terminal dashboard
klawty logs [agent]      # tail logs
klawty --version         # Klawty 1.0.0

Setup & config

klawty onboard           # interactive wizard
klawty setup             # initialize workspace
klawty configure         # credentials, channels
klawty config set K V    # set a config value
klawty config get K      # read a config value
klawty doctor            # diagnose issues

Agents & memory

klawty agent --message   # run one agent turn
klawty agents list       # show all agents
klawty memory search Q   # semantic search
klawty memory reindex    # rebuild embeddings

Channels & plugins

klawty channels list     # connected channels
klawty channels login    # connect new channel
klawty plugins list      # loaded plugins
klawty skills list       # available skills

Security & ops

klawty security audit    # scan for vulnerabilities
klawty sandbox list      # Docker exec containers
klawty backup create     # snapshot state
klawty backup restore    # restore from snapshot
klawty update            # check for updates
klawty models list       # configured models

Docker exec sandbox

When an agent runs shell commands, they execute inside a Docker container with no network access, read-only root filesystem, 512MB memory limit, and a 30-second timeout. If Docker isn't available, the policy enforcer validates commands before native execution. This prevents agents from affecting the host system.

Policy engine

klawty-policy.yaml defines what agents can do. Network: only allowlisted endpoints are reachable. Filesystem: write only to workspace/, data/, backups/. Execution: blocked dangerous patterns (rm -rf, sudo, curl|bash). Deny-by-default — everything not explicitly allowed is blocked.

Runtime integrity

On every boot, Klawty verifies all runtime modules against SHA-256 hashes in a manifest file. If any critical file has been tampered with, the system degrades to read-only mode. This protects against both accidental corruption and malicious modification.

Exec sandbox

When an agent runs a shell command via the exec tool, it executes inside a Docker container with no network access, read-only root filesystem, 512MB memory limit, and a 30-second timeout. If Docker isn't available, the policy enforcer validates the command against blocked patterns before execution.

Privacy router

Detects PII (email addresses, phone numbers, credit card numbers, IBANs) in task content. When detected, can route inference to a local model (Ollama), redact sensitive data, or block the task entirely. Configurable via klawty-policy.yaml privacy section.

Credential management

API keys are stored with chmod 600 permissions (owner-only read). The credential monitor validates all configured keys against their respective APIs every 6 hours and alerts on expiry, revocation, or low balance (OpenRouter: warns at $5, critical at $1).

Supported channels

Discord · Slack · Telegram · WhatsApp · Signal · Matrix · MS Teams · IRC · Line · Nostr · Terminal · Web · iMessage (macOS) · Google Chat (beta) · Mattermost (beta) · Twitch (beta). Connect via: klawty channels login

Terminal (default)

The terminal channel is always available. Run klawty tui for the interactive dashboard, or klawty agent --message "your message" for single-turn conversations.

Adding a channel

Docker in the free version

The free version uses Docker only for the exec sandbox (isolating shell commands). There is no Qdrant vector memory in the free version — memory is file-based (MEMORY.md). Docker is optional: without it, the exec tool runs natively with policy enforcement.

Running with Docker

Running without Docker

Docker is not required. Install normally and run klawty run. The exec sandbox falls back to native execution with policy checks. Memory uses MEMORY.md files. Everything works the same.

Qdrant vector memory (premium)

The premium version includes 4-tier memory with Qdrant vector search — agents find past knowledge by meaning, not keywords. Docker Compose is pre-configured to start Qdrant automatically. Available at ai-agent-builder.ai.

Agent not starting

Run klawty doctor for diagnostics. Common issues: (1) Missing API key — check .env has OPENROUTER_API_KEY. (2) Gateway not running — run klawty gateway first. (3) Node.js version — requires 22+, run node --version.

No API key error

Klawty uses auth profiles per provider. Set up OpenRouter:

klawty configure --section model
# Or manually create auth profile:
mkdir -p ~/.klawty/agents/main/agent
echo '{"profiles":[{"provider":"openrouter","apiKey":"sk-or-v1-YOUR-KEY","label":"default","isDefault":true}]}' > ~/.klawty/agents/main/agent/auth-profiles.json

Empty dashboard

The Control UI needs to be built: pnpm ui:build. Then restart the gateway. Access via http://127.0.0.1:2508/?token=YOUR_TOKEN (token is in ~/.klawty/klawty.json under gateway.auth.token).

High AI costs

Check your model configuration. The free version uses a single model with no routing optimization. Premium includes 5-tier routing that reduces costs by 10x. For now, use a cheaper model: klawty config set agents.defaults.model.primary openrouter/google/gemini-2.5-flash

CSP errors in browser

Content Security Policy blocks may appear if the gateway's inline scripts aren't allowed. This is fixed in v1.0.0 with 'unsafe-inline' in script-src. If you're seeing CSP errors, rebuild: pnpm build && pnpm ui:build.

What premium adds

Up to 8 coordinated agents · 27-module production runtime (10,235 lines) · 5-tier LLM routing (10x cost savings) · 4-tier memory with Qdrant vectors · 27 domain skills + self-improvement · Proposal lifecycle with rollback · 4-layer deduplication · Health monitor + backups + scorecard · Management dashboard (web portal) · 6 industry-specific solutions · Managed hosting from 79€/month (all-inclusive: hosting + AI + support).

Self-hosted vs managed

Self-hosted: download a ZIP, run on your machine. You bring your own OpenRouter API key. From 49€ one-time. Managed: we host, deploy, and maintain your agents. AI credits included. Online dashboard at your subdomain. From 79€/month.

Get premium

Visit ai-agent-builder.ai to configure your agent team, choose your industry, and get started. The wizard takes 5 minutes.