Documentation

Everything you need to deploy and operate your AI agent fleet.

Quick Start

Deploy AskAlf in 60 seconds:

git clone https://github.com/SprayberryLabs/askalf.git
cd askalf && ./setup.sh
docker compose -f docker-compose.selfhosted.yml up -d

Open http://localhost:3001 and complete the 5-step onboarding wizard.

Requirements

Docker and Docker Compose
4GB+ RAM (8GB recommended)
At least one AI provider key (Anthropic recommended, OpenAI supported)
Git

Runs on Linux, macOS, and Windows — anything with Docker.

Architecture

Forge

API server, agent runtime, execution engine, scheduler, orchestration

Dashboard

React SPA, mission control, embedded Claude CLI + Codex terminals

MCP Tools

Tool server for agents: tickets, memory, search, docker, security

PostgreSQL + pgvector

Database with vector embeddings for 10-layer cognitive memory

Redis

Pubsub, rate limiting, session cache, queue management

SearXNG

Privacy-respecting web search for agent research

Agent Fleet

7 core agents + unlimited custom specialists spawned on demand:

Agent	Role
Backend Dev	API routes, database, server-side logic, bug fixes
Frontend Dev	React components, UI features, CSS, styling
QA	Tests, validation, regression detection, coverage
Infra	Docker, deployments, infrastructure, CI/CD
Security	Vulnerability scanning, dependency audits, secret detection
Watchdog	Health checks, incident detection, monitoring, alerting
Writer	Documentation, changelogs, runbooks, technical writing

Custom specialists are created on the fly for domain-specific tasks — Terraform, ML Ops, HIPAA compliance, iOS builds, Salesforce, and anything else. They're first-class agents with tickets, memory, and coordination.

Embedded Terminals

The Code tab provides full Claude CLI and OpenAI Codex terminal sessions inside the dashboard. These are real PTY sessions via xterm.js — not wrappers. Your agents' context, MCP tools, and knowledge graph are all available.

Cognitive Memory

10-layer brain system with pgvector embeddings:

Semantic — Facts, concepts, system architecture
Episodic — What happened, what worked, what failed
Procedural — Reusable patterns extracted from successful operations
Knowledge Graph — 1,500+ nodes with automatic cross-agent connection discovery
Metabolic Consolidation — Overnight cycles that strengthen useful memories and decay noise

Onboarding Wizard

5-step setup on first launch:

Workspace — Name your deployment
AI Config — Choose basic or enhanced intent parser, optionally add API keys
Connect Claude — OAuth flow for Claude CLI (or skip)
Appearance — Dark, light, or system theme
Launch — Review and enter the command center

Dashboard Tabs

Overview

Mission control with orbital fleet visualization, real-time heartbeat, cost telemetry, and event ticker.

Command

Natural language task dispatch. Type what you need — the intent parser routes to the right agent(s).

Code

Embedded Claude Code and OpenAI Codex terminal sessions with full platform MCP tools.

Fleet

Agent management, builder for custom agents, skill templates, delegation graph.

Ops

Tickets, costs, executions, timeline, orchestrator, providers, guardrails, audit log, workflows, deploy.

Live

Real-time WebSocket event stream with agent and type filtering.

Brain

Memory browser, knowledge graph visualization, analytics with consolidation cycles.

Settings

Profile, appearance, providers (AI keys), API keys, cost controls, integrations (22), channels (15), devices (12).

Device Adapters

12 adapter types for connecting devices to your fleet:

CLI Agent · Docker · SSH · Kubernetes · Browser · Desktop · VS Code · Android · iOS · Raspberry Pi · Arduino/ESP32 · Home Assistant

CLI Agent

npm install -g @askalf/agent

# Connect this device to your fleet
askalf-agent connect <your-api-key>

# Connect to a self-hosted instance
askalf-agent connect <your-api-key> --url wss://your-server.com

# Run as a background daemon
askalf-agent daemon

# Check connection status
askalf-agent status

# Disconnect
askalf-agent disconnect

Flag	Description	Default
`--url <url>`	Server WebSocket URL	`wss://askalf.org`
`--name <name>`	Device display name	System hostname
`--version`	Show version
`--help`	Show help

Config is stored in ~/.askalf/agent.json. The agent auto-detects capabilities (shell, git, docker, node, python) and reports them to the fleet.

API Keys

Generate API keys in Settings → API Keys. Keys use the fk_ prefix, PBKDF2 hashing, per-key rate limits, and optional expiration. Use them with the CLI agent or the REST API.

Optional: VPN Tunneling

Route all outbound agent traffic through an encrypted VPN tunnel using Gluetun. Your agents' API calls, web searches, and external requests are encrypted and anonymous. Supports 30+ VPN providers.

Step 1: Get your VPN credentials

ProtonVPN (WireGuard — recommended):

Log into account.protonvpn.com
Go to Downloads → WireGuard configuration
Generate a key — copy the Private Key

ProtonVPN (OpenVPN):

Go to Account → OpenVPN / IKEv2 username
Copy your OpenVPN username and password

Step 2: Configure your .env

# WireGuard (faster, recommended)
VPN_SERVICE_PROVIDER=protonvpn
VPN_TYPE=wireguard
WIREGUARD_PRIVATE_KEY=your-wireguard-private-key
VPN_SERVER_COUNTRIES=Switzerland

# OR OpenVPN
VPN_SERVICE_PROVIDER=protonvpn
VPN_TYPE=openvpn
OPENVPN_USER=your-openvpn-username
OPENVPN_PASSWORD=your-openvpn-password
VPN_SERVER_COUNTRIES=Switzerland

Step 3: Start with VPN

docker compose -f docker-compose.selfhosted.yml --profile vpn up -d

To also route SearXNG searches through the VPN, swap the search config:

# In docker-compose.selfhosted.yml, change the searxng volume:
# from: ./infrastructure/searxng/settings.yml
# to:   ./infrastructure/searxng/settings-vpn.yml

This enables Google, Google Scholar, Mojeek, and Qwant (blocked without VPN) and routes all search traffic through the tunnel.

Choose your country

Change VPN_SERVER_COUNTRIES to any country your provider supports:

VPN_SERVER_COUNTRIES=Netherlands
VPN_SERVER_COUNTRIES=Japan
VPN_SERVER_COUNTRIES=United States

Other VPN providers

Not on ProtonVPN? Change VPN_SERVICE_PROVIDER. Gluetun supports:

Mullvad · NordVPN · Surfshark · ExpressVPN · Private Internet Access · Windscribe · CyberGhost · IPVanish · AirVPN · and 30+ more.

Optional: Autoheal

Automatic container recovery. If any AskAlf container fails its health check, Autoheal restarts it automatically. Zero-downtime self-healing. Already included in the compose file — runs by default.

Source Code

Full source available on GitHub: github.com/SprayberryLabs/askalf

Support

Email support@askalf.org or open an issue on GitHub.