Skip to content

AlexClaw 🦇

A BEAM-native personal autonomous AI agent built on Elixir/OTP.

AlexClaw monitors the world — RSS feeds, GitHub repositories, Google services, arbitrary APIs — accumulates knowledge, executes workflows autonomously on schedule, and communicates with its owner via Telegram or Discord. Every task is routed to the cheapest available LLM that satisfies the required reasoning tier, including fully local models.

Designed as a single-user personal agent. Not a platform. Not a marketplace. One codebase, fully auditable, running on your infrastructure.


Why AlexClaw?

  • BEAM-native — OTP supervision, concurrency, and fault tolerance are the runtime, not bolted on. A failed RSS fetch cannot crash a concurrent research query.
  • Cost-aware — tier-based LLM routing maximises free tiers across providers. Fully local (zero API cost) deployments are supported.
  • Runtime-configurable — all settings live in PostgreSQL, cached in ETS, editable via admin UI without restart.
  • Single-user, fully auditable — no multi-tenant complexity, no marketplace, no platform overhead.

Quick Start

git clone https://github.com/thatsme/AlexClaw.git
cd AlexClaw
cp .env.example .env
# In .env: DATABASE_OWNER_PASSWORD, DATABASE_PASSWORD, SECRET_KEY_BASE,
# ADMIN_PASSWORD, CLUSTER_COOKIE and TELEGRAM_CHAT_ID.
mkdir -p openbao/unseal
head -c 32 /dev/urandom > openbao/unseal/key && chmod 0440 openbao/unseal/key
docker compose up -d
docker compose run --rm openbao-init   # once: prints the recovery key

Open http://localhost:5001 and log in with ADMIN_PASSWORD. Set up 2FA (Services page), then on the Config page enter the Telegram bot token, an LLM API key (Gemini's is free) and telegram.owner_user_id — the bot answers only that user, in telegram.chat_id. Send /ping to the bot to verify.

The unseal key file encrypts every secret: losing it loses them all. The full first-start procedure, including the file ownership Linux needs, is in OpenBao.

Full setup walkthrough: Installation


Feature Overview

Area What it does
Multi-Model LLM Router Tier-based routing (light/medium/heavy/local) with priority ordering, daily usage tracking, and automatic fallback
Workflow Engine Linear pipelines with conditional branching, per-step circuit breaking, and full run history
Persistent Memory PostgreSQL + pgvector, hybrid semantic + keyword search, async background embedding
Dynamic Skills Upload .ex skill modules at runtime — contained to an allowlist, permission-checked, 2FA-approved, integrity-checksummed
Forge Generates new skills from a goal, with a local or a chosen provider. Contained code within the unattended permissions loads at once; more permissions wait for a 2FA code; calls outside the allowlist never load
Secrets in OpenBao Every credential in a bundled OpenBao, bound to its destination; the database holds references
Multi-Gateway Telegram + Discord simultaneously. Responses route back to the originating transport
Multi-Node Clustering Multiple BEAM nodes share a database and exchange workflow outputs over Erlang distribution
OTP Circuit Breaker Per-skill breaker with automatic half-open recovery. No external dependencies
SQL Read The sql_query workflow step runs one fixed, parameterised read on a PostgreSQL connection defined on the Connections page; the password is kept in OpenBao and the query is checked on the database when the step is saved

Architecture in One Diagram

Telegram ──> TelegramGateway ──┐
Discord  ──> DiscordGateway  ──┴──> Dispatcher ──> Skills
                                         │              │
                               Workflows.Executor    SkillSupervisor
                                         │         (DynamicSupervisor)
                                    LLM Router
                          (Gemini / Anthropic / Ollama / LM Studio)
                                         │
                           ┌─────────────┴─────────────┐
                        Memory                       Config
                 (pgvector + embeddings)         (DB + ETS + PubSub)

→ Full architecture documentation


Requirements

  • Docker and Docker Compose v2
  • 2 GB RAM minimum
  • A Telegram bot token (from @BotFather)
  • At least one LLM provider — Gemini API key is free and takes 2 minutes
  • A place to keep OpenBao's unseal key file and recovery key offline (the key file is made before the first start, the recovery key is printed at it)