---

name: moltbot description: Moltbot AI assistant gateway - multi-channel LLM integration platform. Use when configuring moltbot.json, setting up Telegram/Discord/WhatsApp channels, managing agents, authentication profiles, tools, skills, or plugins. Also use when creating new Claude Code skills or understanding skill structure.

Moltbot

Moltbot is a multi-channel AI assistant gateway that connects LLMs to messaging platforms like Telegram, Discord, and WhatsApp.

Documentation: https://docs.molt.bot/

Quick Start

Skill Creation

Creating skills for moltbot follows the same structure as Claude Code skills:

skill-name/
├── SKILL.md           # Required: metadata + instructions
├── scripts/           # Optional: executable code
├── references/        # Optional: documentation
└── assets/            # Optional: templates, files for output

For detailed skill authoring: See references/skill-creation.md

Configuration

Moltbot configuration lives in moltbot.json:

{
  "agents": { ... },      // LLM agents and models
  "channels": { ... },    // Telegram, Discord, etc.
  "auth": { ... },        // API key profiles
  "tools": { ... },       // Web search, fetch, etc.
  "skills": { ... },      // Skill installation settings
  "plugins": { ... }      // Platform plugins
}

For configuration details: See references/configuration.md

Deployment (This Repo)

Moltbot runs as a Proxmox LXC container.

Files:

• NixOS config: nixos/machines/moltbot.nix
• Secrets: private/nixos/secrets/moltbot/*.age
• Skills: private/nixos/machines/resources/moltbot/skills/

Deploy:

rebuild -vL moltbot  # Build locally and push to LXC

Key paths on LXC:

• Config: /var/lib/moltbot/.moltbot/moltbot.json (managed dynamically, not via Nix)
• Workspace: /var/lib/moltbot/workspace
• Skills: /var/lib/moltbot/.moltbot/skills/
• Auth profiles: /var/lib/moltbot/.moltbot/agents/main/agent/auth-profiles.json

Core Concepts

Agents

Agents are LLM instances with configured models, workspaces, and capabilities.

{
  "agents": {
    "defaults": {
      "model": { "primary": "google/gemini-3-pro-preview" },
      "models": {
        "anthropic/claude-sonnet-4-5": { "alias": "sonnet" },
        "google/gemini-3-pro-preview": { "alias": "gemini" }
      },
      "workspace": "/var/lib/moltbot/workspace",
      "thinkingDefault": "medium"
    },
    "list": [{ "id": "main", "default": true }]
  }
}

Channels

Channels connect moltbot to messaging platforms.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": [28814201],
      "groupPolicy": "allowlist"
    }
  }
}

Authentication

API keys are managed via auth profiles:

{
  "auth": {
    "profiles": {
      "anthropic:default": { "provider": "anthropic", "mode": "token" },
      "google:default": { "provider": "google", "mode": "api_key" }
    }
  }
}

Actual credentials go in auth-profiles.json (generated by systemd service from agenix secrets).

MUST DO

• Always consult https://docs.molt.bot/ before making configuration changes
• Use rebuild -vL moltbot for deployments (builds locally, prevents timeouts)
• Test changes with journalctl -u moltbot-gateway -f on the LXC

MUST NOT

• Commit API keys or tokens to git (use agenix secrets)
• Guess configuration formats - check documentation first
• Modify auth-profiles.json directly (it's generated from secrets)

Moltbot Skills vs Claude Code Skills

Moltbot skills and Claude Code skills are separate systems with similar format (SKILL.md with frontmatter) but different purposes.

Aspect	Claude Code Skills	Moltbot Skills
Used by	Claude Code CLI	Moltbot gateway
Source	home/common/ai/resources/claude-code/skills/	private/nixos/machines/resources/moltbot/skills/
Deployed to	~/.claude/skills/ (local machines)	/var/lib/moltbot/.moltbot/skills/ (LXC)
Registry	N/A	ClawdHub (clawdhub.com)

Adding Moltbot Skills

Moltbot skills teach moltbot how to use tools. To add a skill:

1. Download from ClawdHub or create the skill in private/nixos/machines/resources/moltbot/skills/<skill-name>/
2. Add required binaries (from skill's metadata.requires.bins) to path and systemPackages in moltbot.nix
3. Add tmpfiles rules to deploy the skill to /var/lib/moltbot/.moltbot/skills/

Moltbot handles tool configuration itself based on skill instructions.