🤖 Alvin Bot — Autonomous AI Agent

Your personal AI assistant — on Telegram, WhatsApp, Discord, Signal, Terminal, and Web.

Alvin Bot is an open-source, self-hosted AI agent that lives where you chat. Built on a multi-model engine with full system access, memory, plugins, and a rich web dashboard. Not just a chatbot — an autonomous agent that remembers, acts, and learns.

📸 Preview

💬 Chat (Dark Mode)	📊 Dashboard
🤖 AI Models & Providers	🎭 Personality Editor
💬 Telegram	📱 Messaging Platforms
🔧 Custom Tools	🩺 Health & Maintenance

🖼️ More Screenshots (click to expand)

Feature	Screenshot
Login
Chat (Light)
Memory Manager
Active Sessions
File Browser
Scheduled Jobs
Plugins & MCP
WhatsApp Groups
WA Group Details
User Management
Web Terminal
Settings & Env
Telegram Commands
macOS Installer

✨ Features

🧠 Intelligence

• Multi-Model Engine — Claude (Agent SDK with full tool use), OpenAI, Groq, NVIDIA NIM, Google Gemini, OpenRouter, or any OpenAI-compatible API
• Automatic Fallback — If one provider fails, seamlessly tries the next
• Heartbeat Monitor — Pings providers every 5 minutes, auto-failover after 2 failures, auto-recovery
• User-Configurable Fallback Order — Rearrange provider priority via Telegram (/fallback), Web UI, or API
• Adjustable Thinking — From quick answers (/effort low) to deep analysis (/effort max)
• Persistent Memory — Remembers across sessions via vector-indexed knowledge base; session state (Claude SDK resume tokens, conversation history, language, effort) survives bot restarts (v4.11.0)
• Multi-Session Workspaces — Run multiple parallel, context-isolated sessions on the same bot — one per Slack channel or per Telegram /workspace — each with its own working directory, purpose, and persona. Memory, skills, and sub-agents stay globally shared (v4.12.0). How-to ↓
• Background Sub-Agents — Claude autonomously uses run_in_background: true for long audits/research; main session stays responsive, results deliver as separate messages (v4.10.0)
• Smart Tool Discovery — Scans your system at startup, knows exactly what CLI tools, plugins, and APIs are available
• Skill System — 12 built-in SKILL.md files (code, data analysis, email, docs, research, sysadmin, browse, etc.) auto-activate based on message context
• Self-Awareness — Knows it IS the AI model — won't call external APIs for tasks it can do itself
• Automatic Language Detection — Detects user language (EN/DE/ES/FR) and adapts; learns preference over time

💬 Multi-Platform

• Telegram — Full-featured with streaming, inline keyboards, voice, photos, documents
• Slack — Socket Mode bot via @slack/bolt, DMs + @mentions, file attachments, reactions, assistant.threads.setStatus typing indicator. One channel = one isolated workspace. See Multi-Session Workspaces below.
• WhatsApp — Via WhatsApp Web: self-chat as AI notepad, group whitelist with per-contact access control, full media support (photos, docs, audio, video)
• WhatsApp Group Approval — Owner gets approval requests via Telegram (or WhatsApp DM fallback) before the bot responds to group messages. Silent — group members see nothing.
• Discord — Server bot with mention/reply detection, slash commands
• Signal — Via signal-cli REST API with voice transcription
• Terminal — Rich TUI with ANSI colors and streaming (alvin-bot tui)
• Web UI — Full dashboard with chat, settings, file manager, terminal, workspace overview

🔧 Capabilities

• 52+ Built-in Tools — Shell, files, email, screenshots, PDF, media, git, system control
• Plugin System — 6 built-in plugins (weather, finance, notes, calendar, email, smarthome)
• MCP Client — Connect any Model Context Protocol server
• Cron Jobs — Scheduled tasks with AI-driven creation ("check my email every morning")
• Voice — Speech-to-text (Groq Whisper) + text-to-speech (Edge TTS)
• Vision — Photo analysis, document scanning, screenshot understanding
• Image Generation — Via Google Gemini / DALL·E (with API key)
• Web Browsing — Fetch and summarize web pages

🖥️ Web Dashboard

• Live Chat — WebSocket streaming, same experience as Telegram
• Model Switcher — Change AI models on the fly
• Platform Setup — Configure all messengers and providers via UI, WhatsApp group management inline
• File Manager — Browse, edit, create files in the working directory
• Memory Editor — View and edit the agent's knowledge base
• Session Browser — Inspect conversation history
• Terminal — Run commands directly from the browser
• Maintenance — Health checks, backups, bot controls

🚀 Quick Start

npm install -g alvin-bot
alvin-bot setup
alvin-bot start

That's it. The setup wizard validates everything:

• ✅ Tests your AI provider key
• ✅ Verifies your Telegram bot token
• ✅ Confirms the setup works before you start

Requires: Node.js 18+ (nodejs.org) · Telegram bot token (@BotFather) · Your Telegram user ID (@userinfobot)

Free AI providers available — no credit card needed. Privacy-first? Pick the 🔒 Offline — Gemma 4 E4B option in setup for a fully local LLM via Ollama (macOS/Linux: automated install; Windows: manual).

📘 First-time setup walkthroughs

Step-by-step guides with screenshots and screen-for-screen instructions:

Both guides cover: Node.js install · Telegram bot creation · first-time setup · foreground test · background service · offline Gemma 4 mode · troubleshooting. ~15 min end-to-end for a first-time user.

macOS: use launchd instead of pm2 (recommended)

If you're on macOS and using Claude Code (Max subscription) as your provider, run the bot as a LaunchAgent — it inherits the GUI login session so the macOS Keychain stays unlocked and the Claude OAuth token just works without any manual security unlock-keychain dance:

alvin-bot launchd install    # writes ~/Library/LaunchAgents/com.alvinbot.app.plist and starts the agent
alvin-bot launchd status     # show PID + recent stdout/stderr logs
alvin-bot launchd uninstall  # unload + remove the plist

Pm2 still works and remains the default on Linux/Windows — but on macOS with Claude Code, launchd is the only path that reliably keeps Keychain access over restarts.

📖 Handbook

For a full walkthrough of everything Alvin Bot can do — providers, sub-agents, cron jobs, plugins, MCP, security audit, web UI — read docs/HANDBOOK.md.

AI Providers

*Claude SDK requires a Claude Max subscription ($20/mo) or Anthropic API access. The setup wizard checks this automatically.

Alternative Installation

curl -fsSL https://raw.githubusercontent.com/alvbln/Alvin-Bot/main/install.sh | bash

git clone https://github.com/alvbln/Alvin-Bot.git
cd Alvin-Bot
cp .env.example .env    # Edit with your tokens
docker compose up -d

git clone https://github.com/alvbln/Alvin-Bot.git
cd Alvin-Bot
npm install
npm run build
node bin/cli.js setup   # Interactive wizard
npm run dev             # Start in dev mode

npm install -g pm2
pm2 start ecosystem.config.cjs
pm2 save && pm2 startup

Troubleshooting

alvin-bot doctor        # Check configuration & validate connections

If your AI provider isn't working, run doctor — it tests the actual API connection and shows exactly what's wrong.

📋 Commands

🏗️ Architecture

                            ┌──────────────┐
                            │   Web UI     │ (Dashboard, Workspaces, Chat, Settings)
                            └──────┬───────┘
                                   │ HTTP/WS
┌──────────┐  ┌───────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│ Telegram │  │ Slack │  │ WhatsApp │  │ Discord  │  │  Signal  │
└────┬─────┘  └───┬───┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
     │            │           │             │              │
     └────────────┴───────────┴─────────────┴──────────────┘
                           │
                 ┌─────────┴──────────┐
                 │ Workspace Resolver │ (per-channel context: cwd + persona)
                 └─────────┬──────────┘
                           │
                    ┌──────┴───────┐
                    │   Engine     │ (Query routing, fallback)
                    └──────┬───────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
   ┌──────┴──────┐  ┌─────┴──────┐  ┌──────┴──────┐
   │ Claude SDK  │  │  OpenAI    │  │  Custom     │
   │ (full agent)│  │ Compatible │  │  Models     │
   └─────────────┘  └────────────┘  └─────────────┘

Provider Types

Universal Tool Use: Alvin Bot gives full agent capabilities to any provider that supports function calling — not just Claude. Shell commands, file operations, Python execution, web search, and more work across all major providers. If a provider doesn't support tool calls, Alvin Bot automatically falls back to text-only chat mode.

Project Structure

alvin-bot/
├── src/
│   ├── index.ts                 # Entry point
│   ├── engine.ts                # Multi-model query engine
│   ├── config.ts                # Configuration
│   ├── handlers/                # Message & command handlers
│   ├── middleware/              # Auth & access control
│   ├── platforms/               # Telegram, Slack, WhatsApp, Discord, Signal adapters
│   ├── providers/               # AI provider implementations
│   ├── services/                # Memory, voice, cron, plugins, workspaces, tool discovery
│   ├── tui/                     # Terminal UI
│   └── web/                     # Web server, APIs, setup wizard
├── web/public/                  # Web UI (HTML/CSS/JS, zero build step)
├── plugins/                     # Plugin directory (6 built-in)
├── docs/
│   ├── install/                 # Setup guides (macOS, Windows, Slack)
│   └── custom-models.json       # Custom model configurations
├── TOOLS.md                     # Custom tool definitions (Markdown)
├── SOUL.md                      # Agent personality
├── bin/cli.js                   # CLI entry point
└── ecosystem.config.cjs         # PM2 configuration

🧭 Multi-Session Workspaces (v4.12.0)

Run multiple parallel Alvin sessions on the same bot — one per project, context-isolated, memory shared. Think Claude Coworker, but on your own machine with your own tools. Each workspace has its own working directory, purpose, and optional persona. Sub-agents spawned in one workspace stay in that workspace. Memory, skills, and the knowledge base are globally shared across all of them.

Why you'd want this

Without workspaces, Alvin has one big blob of context. If you ask about Alev-B deployment right after debugging a trading bot, Claude pollutes one context with the other. Workspaces solve this: Slack channel = session, or on Telegram, /workspace alev-b = session. Each one has its own Claude SDK resume token, history, and current project CLAUDE.md loaded via its working directory.

How it works

1. Drop a markdown file into ~/.alvin-bot/workspaces/<name>.md with YAML frontmatter.
2. Alvin hot-reloads the workspace registry (no restart needed — same pattern as skills).
3. On Slack, workspaces resolve by explicit channel ID first, then by channel name match (#alev-b → workspaces/alev-b.md, case-insensitive).
4. On Telegram, run /workspace <name> to switch — next message uses the new persona and cwd.
5. Nothing configured? Alvin falls back to the "default" workspace exactly like pre-v4.12 — no breaking changes.

Example workspace file

Create ~/.alvin-bot/workspaces/alev-b.md:

---
purpose: Alev-B consulting website dev
cwd: ~/Projects/alev-b-website
emoji: "🏢"
color: "#6366f1"
channels: ["C01ABCDEF"]
---
You are focused on the Alev-B consulting website. Stack: React + Express +
Drizzle + MySQL. Production VPS 72.62.34.230, deploy via rsync. Prefer
concise, directly actionable answers about features, deployment, and
Stripe integration.

The cwd auto-loads the project-specific CLAUDE.md via Claude SDK's settingSources: ["user", "project"], so each workspace inherits its project's conventions automatically. channels is optional — omit it to match by filename.

Slack setup (5 minutes)

1. Download the setup guide + manifest from the latest release:
   • slack-setup.md — step-by-step instructions with screenshots
   • slack-manifest.json — copy-paste ready Slack App manifest
2. Create a Slack App from the manifest at https://api.slack.com/apps → Create New App → From an app manifest
3. Enable Socket Mode, generate an App-Level Token (starts with xapp-)
4. Install the app to your workspace, copy the Bot User OAuth Token (starts with xoxb-)
5. Add both to ~/.alvin-bot/.env:

   SLACK_APP_TOKEN=xapp-1-...
   SLACK_BOT_TOKEN=xoxb-...
   SLACK_ALLOWED_USERS=U01ABCDEF      # optional, comma-separated

6. Restart Alvin. You should see 💬 Slack connected (Alvin @ YourWorkspace) in the log.
7. Invite Alvin to channels with /invite @Alvin. DMs work without an invite.

Telegram /workspace commands

Workspace selection is per Telegram user, persisted across bot restarts via ~/.alvin-bot/state/sessions.json (v2 envelope format, backwards compatible with v4.11).

Web UI

The dashboard has a dedicated 🧭 Workspaces tab (Data section in the sidebar). Each workspace shows as a color-coded card with emoji, purpose, cwd, mapped channels, session count, message count, and cumulative cost. Useful for spotting which project is burning the most tokens.

Or query directly:

curl -s http://localhost:3100/api/workspaces | jq

Architecture guarantees

• Memory is global. Facts Alvin learns in #alev-b are visible in #homes via the shared MEMORY.md and embeddings index. Per-workspace memory layer is on the v4.13 roadmap.
• Sub-agents are per-session. Each workspace can spawn its own run_in_background agents — results come back to the same channel automatically (v4.10.0).
• Session state survives restart. Claude SDK resume tokens, conversation history, language, effort, and workspaceName all persist via session-persistence.ts (v4.11.0).
• Backwards compatible. If you don't create any workspace files, everything behaves exactly like v4.11. Upgrade is a no-op.

⚙️ Configuration

Environment Variables

# Required
BOT_TOKEN=<Telegram Bot Token>
ALLOWED_USERS=<comma-separated Telegram user IDs>

# AI Providers (at least one needed)
# Claude SDK uses CLI auth — no key needed
GROQ_API_KEY=<key>              # Groq (voice + fast models)
NVIDIA_API_KEY=<key>            # NVIDIA NIM models
GOOGLE_API_KEY=<key>            # Gemini + image generation
OPENAI_API_KEY=<key>            # OpenAI models
OPENROUTER_API_KEY=<key>        # OpenRouter (100+ models)

# Provider Selection
PRIMARY_PROVIDER=claude-sdk     # Primary AI provider
FALLBACK_PROVIDERS=nvidia-kimi-k2.5,nvidia-llama-3.3-70b

# Optional Platforms
WHATSAPP_ENABLED=true           # Enable WhatsApp (needs Chrome)
DISCORD_TOKEN=<token>           # Enable Discord
SIGNAL_API_URL=<url>            # Signal REST API URL
SIGNAL_NUMBER=<number>          # Signal phone number
SLACK_BOT_TOKEN=xoxb-...        # Slack Bot User OAuth Token (Socket Mode)
SLACK_APP_TOKEN=xapp-1-...      # Slack App-Level Token (connections:write scope)
SLACK_ALLOWED_USERS=U01...      # Optional: comma-separated Slack user IDs allowlist

# Multi-Session (v4.12.0)
SESSION_MODE=per-channel        # per-user (default) | per-channel | per-channel-peer
                                # per-channel gives each Slack channel / group its own isolated session

# Optional
WORKING_DIR=~                   # Default working directory (used when no workspace is resolved)
MAX_BUDGET_USD=5.0              # Cost limit per session
WEB_PORT=3100                   # Web UI port
WEB_PASSWORD=<password>         # Web UI auth (optional)
CHROME_PATH=/path/to/chrome     # Custom Chrome path (for WhatsApp)
MEMORY_EXTRACTION_DISABLED=1    # Opt out of v4.11.0 auto-fact-extraction in compaction

Custom Models

Add any OpenAI-compatible model via docs/custom-models.json:

[
  {
    "key": "my-local-llama",
    "name": "Local Llama 3",
    "model": "llama-3",
    "baseUrl": "http://localhost:11434/v1",
    "apiKeyEnv": "OLLAMA_API_KEY",
    "supportsVision": false,
    "supportsStreaming": true
  }
]

Personality

Edit SOUL.md to customize the bot's personality. Changes apply on /reload or bot restart.

WhatsApp Setup

WhatsApp uses whatsapp-web.js — the bot runs as your own WhatsApp account (not a separate business account). Chrome/Chromium is required.

1. Enable WhatsApp

Set WHATSAPP_ENABLED=true in .env (or toggle via Web UI → Platforms → WhatsApp). Restart the bot.

2. Scan QR Code

On first start, a QR code appears in the terminal (and in the Web UI). Scan it with WhatsApp on your phone (Settings → Linked Devices → Link a Device). The session persists across restarts.

3. Chat Modes

All toggles are also available in the Web UI (Platforms → WhatsApp). Changes apply instantly — no restart needed.

4. Group Whitelist

Groups must be explicitly enabled. In the Web UI → Platforms → WhatsApp → Group Management:

• Enable a group to let the bot listen
• Allowed Contacts — Select who can trigger the bot (empty = everyone)
• @ Mention Required — Bot only responds when mentioned (voice/media bypass this)
• Process Media — Allow photos, documents, audio, video
• Approval Required — Owner must approve each message via Telegram before the bot responds. Group members see nothing — completely transparent.

Note: Your own messages in groups are never processed (you ARE the bot on WhatsApp). The bot only responds to other participants. In self-chat, your messages are always processed normally.

5. Approval Flow (when enabled per group)

1. Someone writes in a whitelisted group
2. You get a Telegram notification with the message preview + ✅ Approve / ❌ Deny buttons
3. Approve → bot processes and responds in WhatsApp. Deny → silently dropped.
4. Fallback channels if Telegram is unavailable: WhatsApp self-chat → Discord → Signal
5. Unapproved messages expire after 30 minutes.

🔌 Plugins

Built-in plugins in plugins/:

Plugins are auto-loaded at startup. Create your own by adding a directory with an index.js exporting a PluginDefinition.

🎯 Skills

Built-in skills in skills/:

Skills activate automatically when your message matches their trigger keywords. The skill's SKILL.md content is injected into the system prompt, giving the agent specialized expertise for that task.

🛠️ CLI

alvin-bot setup     # Interactive setup wizard
alvin-bot tui       # Terminal chat UI ✨
alvin-bot chat      # Alias for tui
alvin-bot doctor    # Health check
alvin-bot update    # Pull latest & rebuild
alvin-bot start     # Start the bot (background via pm2)
alvin-bot start -f  # Start in foreground
alvin-bot stop      # Stop the bot
alvin-bot launchd install    # macOS only: install as LaunchAgent
alvin-bot launchd status     # macOS only: show LaunchAgent state
alvin-bot launchd uninstall  # macOS only: remove LaunchAgent
alvin-bot audit     # Security health check
alvin-bot search    # Search assets/memories/skills
alvin-bot version   # Show version

🗺️ Roadmap

• Phase 1 — Multi-Model Engine (provider abstraction, fallback chains)
• Phase 2 — Memory System (vector search, user profiles, smart context)
• Phase 3 — Rich Interactions (video messages, browser automation, email)
• Phase 4 — Plugins & Tools (plugin ecosystem, MCP client, custom tools)
• Phase 5 — CLI Installer (setup wizard, Docker, health check)
• Phase 6 — Web Dashboard (chat, settings, file manager, terminal)
• Phase 7 — Multi-Platform (Telegram, Discord, WhatsApp, Signal adapters)
• Phase 8 — Universal Tool Use (NEW) — All providers get agent powers:
  • ✅ Shell execution, file read/write/edit, directory listing
  • ✅ Python execution (Excel, PDF, charts, data processing)
  • ✅ Web fetch & search
  • ✅ Auto-detect function calling support per provider
  • ✅ Graceful fallback to text-only for providers without tool support
• Phase 9 — Skill System + Self-Awareness + Language Adaptation:
  • ✅ SKILL.md files for specialized domain knowledge (email, data analysis, code, docs, research, sysadmin)
  • ✅ Auto-matching: skill triggers activate contextual expertise on demand
  • ✅ Self-Awareness Core: agent knows it IS the AI (no external LLM calls for text tasks)
  • ✅ Automatic language detection and adaptation (EN default, learns user preference)
  • ✅ Human-readable cron schedules + visual schedule builder in WebUI
  • ✅ Platform Manager refactor: all adapters via unified registration system
  • ✅ Cron notifications for all platforms (Telegram, WhatsApp, Discord, Signal)
  • ✅ PM2 auto-refresh on Maintenance page
  • ✅ WhatsApp group whitelist with per-contact access control
  • ✅ Owner approval gate (Telegram → WhatsApp DM → Discord → Signal fallback)
  • ✅ Full media processing: photos, documents, audio/voice, video across all platforms
  • ✅ File Browser: create, edit, delete files with safety guards
  • ✅ Git history sanitized (personal data removed via git-filter-repo)
• Phase 10 — Anthropic API Provider + WebUI Provider Management
  • Anthropic API key test case in WebUI (validation endpoint)
  • "Add Provider" flow in WebUI — add new providers post-setup without editing .env
  • Claude SDK guided setup from WebUI (install check, login status, step-by-step)
  • .env.example update with ANTHROPIC_API_KEY
• Phase 11 — WebUI Professional Redesign
  • Replace emoji icons with Lucide SVG icons (60+ icons, sidebar, pages, buttons)
  • i18n framework (i18n.js) — bilingual DE/EN with browser-locale detection (~400 keys)
  • Language toggle in sidebar footer (DE | EN)
  • Typography upgrade (Inter webfont via Google Fonts)
  • Gradient accents + subtle glassmorphism on cards
  • Smooth page transitions (fade animation on page switch)
  • Skeleton loading states + status pulse animations
  • Command Palette (Cmd+K / Ctrl+K) with fuzzy search
• Phase 12 — Native Installers (Non-Techie Friendly)
  • Electron wrapper (embedded Node.js + WebUI + tray icon)
  • macOS .dmg build via electron-builder (arm64)
  • Windows .exe (NSIS) via electron-builder
  • Linux .AppImage + .deb via electron-builder
  • Auto-update mechanism (electron-updater)
  • GUI Setup Wizard (provider selection, Telegram token, first-run experience)
  • Homebrew formula (brew install alvin-bot)
  • Scoop manifest for Windows
  • One-line install script
  • Docker Compose polish (production-ready docker-compose.yml)
• Phase 13 — npm publish (security audit)
• Phase 14 — Async Sub-Agents (v4.10.0)
  • run_in_background: true system prompt hint for Claude SDK
  • Async-agent watcher polling outputFile JSONL, delivering results as separate messages
  • Session-bound sub-agents (each session spawns its own background workers)
• Phase 15 — Memory Persistence + Smart Loading (v4.11.0)
  • Session persistence across bot restarts (debounced atomic flush, v2 envelope)
  • SDK memory injection (MEMORY.md in every system prompt, not just tool-call dependent)
  • Semantic recall on SDK first-turn via embeddings
  • Layered memory stack (L0 identity / L1 preferences / L2 projects / L3 vector search)
  • Auto-fact extraction during compaction (Mem0-style)
• Phase 16 — Multi-Session + Slack Interface (v4.12.0)
  • Session-key fix: platform-message.ts routes through buildSessionKey()
  • Workspace registry with hot-reload (~/.alvin-bot/workspaces/*.md)
  • Workspace resolver in platform handlers (per-channel persona + cwd)
  • Slack adapter polish: progress ticker (chat.update), typing status (assistant.threads.setStatus), channel name cache
  • Telegram /workspace + /workspaces commands (feature parity)
  • Per-workspace cost aggregation + Web UI workspace cards
  • Slack setup guide + copy-paste app manifest (in GitHub Release assets)
• Phase 17 — Memory + Workspace polish (v4.13.0+)
  • SQLite migration of the embeddings index (currently 128 MB JSON)
  • Per-workspace memory layer (additive over global) — facts learned in #alev-b stay in alev-b unless explicitly promoted to global
  • Per-workspace provider override (provider: in frontmatter) — e.g. Alev-B uses Claude Opus, JobSnack uses cheap Gemini
  • Per-workspace skill allowlist — scope Apple Notes to personal workspace, sysadmin only to devops workspace, etc.
  • Multi-User Slack (real per-channel-peer mode) — different users in the same Slack channel get their own sub-sessions
  • Workspace cloning / templates — /workspace clone alev-b as homes-dev spins up a new workspace from an existing one
  • Slack slash commands (/alvin workspace, /alvin status, /alvin new) — native Slack command integration via Bolt
  • Daily log decay / archive — older daily logs move to cold storage after N days
• Phase 18 — Security + Platform hardening (from v4.12.1 audit, prioritized)
  • P1 — Electron major upgrade (35 → 41+) — fixes 1 HIGH + 5 MODERATE Electron CVEs in the Desktop-Build path. Major version jump, requires full rebuild + test of .dmg flow. Separate release (likely bundled with Windows .exe work).
  • P1 — Prompt injection defense strategy — not a single fix but a design debate: heuristic filters vs allow-list vs no-sandbox-accept-the-risk. Currently handled as a documented design-constraint (README security section), not as a code filter. When we decide the policy, implement it across all message entry points.
  • P2 — TypeScript 5 → 6 upgrade — major release, likely breaking changes in strict mode. Needs a dedicated release + test sweep. Low priority since 5.x is still supported.
  • P0 for v5.0 — MCP plugin sandboxing — currently MCP servers run with full Node privileges. Plan: run each MCP in a child process with restricted FS + network policy (similar to deno-permission model). Architectural change, v5.0 territory.

🔒 Security

⚠️ Important: Alvin has full shell + filesystem access

Alvin Bot is an autonomous AI agent built on the Claude Agent SDK with shell, filesystem, and network access to the machine it runs on. This is by design — it's the point of the project. But it means:

• Treat the bot like sudo access — only install it on machines where you'd trust Claude Code to run without supervision.
• Never expose the Web UI (port 3100) to the internet without HTTPS, rate limiting, and a strong WEB_PASSWORD. It binds to localhost by default.
• On multi-user systems, verify ~/.alvin-bot/.env is chmod 600 (v4.12.2+ enforces this automatically on startup).
• ALLOWED_USERS is your first line of defense — v4.12.2+ refuses to start if it's empty and Telegram is enabled.

Read the full threat model and hardening guide: docs/security.md

Access control

• User whitelist — Only ALLOWED_USERS can interact with the bot (hard-enforced at startup since v4.12.2)
• WhatsApp group approval — Per-group participant whitelist + owner approval gate via Telegram (with WhatsApp DM / Discord / Signal fallback). Group members never see the approval process.
• Slack allowlist — SLACK_ALLOWED_USERS restricts who can DM or @mention the bot in Slack
• DM pairing — Optional 6-digit code flow for new users via owner approval (AUTH_MODE=pairing)

Execution hardening

• EXEC_SECURITY=allowlist (default) — Shell commands must match a whitelist of safe binaries and cannot contain shell metacharacters (;, |, &, `, $(...), redirects). Rejected by v4.12.2's exec-guard metachar filter.
• Cron shell jobs go through the same exec-guard (v4.12.2+) — cron is no longer a bypass vector.
• Sub-agent toolset presets — spawn sub-agents with toolset: "readonly" or "research" to restrict what they can do, regardless of the parent's privileges.
• Timing-safe webhook auth — POST /api/webhook uses crypto.timingSafeEqual (v4.12.2+) to prevent timing side-channel token extraction.

Data hardening

• Self-hosted — Your data stays on your machine. No cloud sync, no external logging of prompts or responses.
• No telemetry — Zero tracking, zero analytics, zero phone-home.
• File permissions — .env, sessions.json, memory logs, cron jobs, and all sensitive state files are chmod 0o600 on every write and repaired at startup (v4.12.2+).
• Owner protection — Owner account cannot be deleted via UI.
• Encrypted sudo credentials — If you enable sudo exec, passwords are stored encrypted with an XOR key in a separate file, both chmod 0o600.

Known limitations (documented honestly)

• Prompt injection cannot be reliably filtered — we document this as a capability tradeoff rather than pretending to solve it. See docs/security.md for the full discussion.
• Not yet hardened for public-internet deployment — current scope is "on your own machine". VPS deployment works but requires additional reverse-proxy + TLS + rate-limit setup that we don't automate.
• Electron Desktop build has known CVEs (Phase 18 roadmap). The primary distribution is npm global install, not Desktop — if you don't use the Desktop wrapper, you're not affected.

📄 License

MIT — See LICENSE.

🤝 Contributing

Issues and PRs welcome! Please read the existing code style before contributing.

git clone https://github.com/alvbln/Alvin-Bot.git
cd alvin-bot
npm install
npm run dev    # Development with hot reload