ALF is a self-hosted, always-online personal AI assistant written in Go that runs on the user's own hardware and interacts with users primarily through Telegram chat. It connects to the LLM chosen by the user and builds around it semantic long-term memory, configurable response tiers, voice transcription, media processing, and a web control center, all packaged in a single user-controllable Docker container. The project emphasizes privacy and self-control, relying on no cloud services other than the configured backend.
[Main Capabilities] Flexible backends: Supports three backend families and allows mixing them across different response tiers. CLI backends can use a locally installed Claude Code (using a Claude Pro/Max subscription, flat rate) or OpenAI Codex (codex exec using a ChatGPT Plus subscription). API backends are compatible with any OpenAI-compatible HTTP endpoint, with presets for OpenRouter (single-key access to 200+ models), OpenAI, and the Anthropic API, and custom base_urls can also be registered. Local backends support Ollama, allowing any local model with no API key required. Conversation context flows seamlessly when switching backends. Semantic long-term memory: Uses sqlite-vec for vector similarity search and FTS5 for keyword matching, combined with Go-native ONNX Runtime inference (all-MiniLM-L6-v2) for embeddings, with no Python dependency. Provides three memory tools: recall (hybrid semantic and keyword retrieval), remember (stores facts, preferences, decisions, summaries), and forget (deletes memories by ID). Memories are automatically recalled in relevant conversations, and a batch extractor periodically distills conversation logs into new memories. Configurable response tiers: Defines response tiers with different capabilities, and an LLM classifier reads messages and routes them. Greetings are answered immediately by a cheap model, while complex tasks enter multi-turn deep model sessions with full tool access. Voice and media: Telegram voice messages are transcribed by a separate whisper-service container (faster-whisper) and then handled as ordinary messages. Images are forwarded to the model's vision capabilities (when supported by the backend); videos/GIFs have keyframes extracted to generate contact sheets and their audio transcribed; PDFs have text extracted with pdftotext; documents are passed to the model with appropriate context. Tools and skills: At startup, discovery CLI Tools and skills. System tools are located in tools.d/ (read-only), user tools in tools/; skills likewise use skills.d/ and skills/. All tools support --help, which ALF runs before first use. Adding capabilities only requires placing an executable file into tools/ or a skill definition into skills/. Multi-agent coordination: the orchestrator (Opus) can break down requests, delegate subtasks to agents such as research, writing, and review, review the results, and synthesize the final answer. Each agent works in an isolated session, and contexts do not leak into one another. Teams are defined in JSON files under config.d/agents/, come with a starter team, and can be triggered via instructions such as "use agents" or by scheduling with --tier agent. Scheduled tasks: based on Cron and supporting time zones, providing four execution modes: LLM tasks (run prompts by tier), direct tasks (execute bash commands), orchestrator tasks (coordinate multiple agents), and reminders (send messages directly to Telegram). Each task can be configured with a timeout, execution logs are recorded, a daily summary aggregates task results, and skills can be injected via --skills. Web control center: port 8080, with sidebar navigation. Features include: Chat (SSE streaming, media upload, reactions, multi-session tabs, Markdown rendering); Home (workspace file browsing, memory feeding, administrative operations); Terminal (interactive shell inside the container); Tasks (monitor and start agent tasks, approve/reject, delete completed tasks); Schedule (create, edit, and monitor scheduled tasks and view execution logs and filters); Logs (daemon log search and session filtering); Tiers (real-time configuration of response tiers); Firewall (network firewall rules for outbound access, supporting log-only or enforce modes); Vault (secret vault with OAuth2 browser flow, file storage, service credentials); Settings (configuration editor, Telegram settings, backend registration); Docs (built-in documentation); Apps (self-contained apps generated by ALF, which may include background services and automatically appear in the sidebar). Supports dark/light themes (default, catppuccin, sage) and a mobile-first responsive layout with bottom navigation. Authentication is via Telegram magic link (/login command) or bearer token and session cookie; issuing a new magic link revokes all previous sessions; after repeated authentication failures, according to configurableConfigure thresholds and durations to ban IPs. Conversation engine and interaction features: Unified conversation storage records rich message history (text, tool calls, tool results, thinking blocks) in a JSONL ring buffer, preserving context across backend switches. A tier can be set with force_command: true to invoke directly via command (e.g. /opus analyze this), and the session locks to that tier until /new or session timeout; it is also possible to lock by sending only the command without sending a message. Emoji reactions to messages can trigger behavior learning: negative reactions prompt ALF to ask what the problem is and extract lessons, while positive reactions reinforce good behavior. ALF can generate self-contained web apps in data/apps/, each with a sidebar entry, a CSP-sandboxed service, and an optional background service supervised by a daemon (automatic restart on crash, exponential backoff). First-time users receive an automatic onboarding prompt in their first conversation, and the Telegram /start command can trigger it again. ALF also has a rotating personality layer—16 moods (sharp, philosophical, sarcastic, playful, grumpy, zen, detective, etc.) cycle by date and affect only tone, not capability.
[How to use] Prerequisites: Docker and Docker Compose; at least 2 GB of memory recommended; optional Telegram bot token (via @BotFather) and chat ID; and one supported backend (Claude Pro/Max subscription, ChatGPT Plus subscription, any OpenAI-compatible API key, or a local Ollama installation). Installation: an interactive wizard guides you through choosing the installation directory, configuring Telegram credentials, setting up dashboard access (HTTP or HTTPS with Let's Encrypt), starting the containers, and authenticating the selected backend (Claude CLI, Codex CLI, or API key). Once the container is running, the Control Center setup wizard can guide backend selection from the browser (CLI, Codex, API/OpenRouter/OpenAI/Ollama, etc.), tier presets, and optional Telegram configuration. Usage: send a message to the bot on Telegram.
[System requirements] OS is Linux or macOS (Docker required). Minimum memory 512 MB, recommended 2 GB (needed for voice transcription). Disk about 800 MB for Docker images, plus about an additional on the first voice message 600 MB (Whisper model). The network requires outbound HTTPS to Telegram and the API endpoints of the configured backends (Anthropic, OpenAI, OpenRouter, Ollama hosts, etc.).
[Security and Isolation] The entry point first installs packages and sets permissions as root, then drops privileges via setpriv to alfd (uid 1001) and retains only minimal capabilities (setuid, setgid, sys_admin, sys_chroot, chown). LLM subprocesses run as alf (uid 1000), with zero capabilities and a sanitized environment. User separation, filesystem isolation (config.d/ read-only, tools.d/ read-only executable, data directory read-write), Docker secrets mechanism for storing keys, security response headers (HSTS, X-Frame-Options DENY, CSP with SRI, nosniff), rate limiting (anonymous global 15 requests/minute, authenticated users 600 requests/minute; authentication endpoints 5 requests/minute; terminal/SSH endpoints 30 requests/minute, CORS enabled for the control center API), authentication and IP banning, SSRF protection (the vault proxy blocks private/link-local IP ranges and performs DNS-level validation), outbound firewall (allow/deny rules for HTTP/HTTPS proxies by domain). All Docker images are keylessly signed with Cosign via GitHub OIDC and come with SPX-JSON SBOM attestations; the documentation provides a method for verifying image signatures.
[Internal Architecture] The internal code is organized around five core concerns: Capability (tools/skills/apps) is executed by the AI, with tiered access to Memory under Policy constraints within a Sandbox, and Runtime is responsible for orchestrating these four. The rest consists of user-side consumers (cli/, controlcenter/, telegram/, voice/, scheduler/) and operational pipelines (internal/platform/). Dependency rules are enforced by CI (internal/archtest/): only runtime/ may import the four internal blocks, and consumers depend only on runtime/.
[Limitations] The material does not provide specific pricing, model performance evaluations,specific configuration steps and performance data for various backends; this content is not yet available.
