Moltis

Moltis compiles your entire AI gateway — web UI, LLM providers, tools, and all assets — into a single self-contained executable. There’s no Node.js to babysit, no node_modules to sync, no V8 garbage collector introducing latency spikes.

# Quick install (macOS / Linux)
curl -fsSL https://www.moltis.org/install.sh | sh

Why Moltis?

Key Features

• Multiple LLM Providers — Anthropic, OpenAI, Google Gemini, DeepSeek, Mistral, Groq, xAI, OpenRouter, Ollama, Local LLM, and more
• Streaming-First — Responses appear as tokens arrive, not after completion
• Sandboxed Execution — Commands run in isolated containers (Docker or Apple Container)
• MCP Support — Connect to Model Context Protocol servers for extended capabilities
• Multi-Channel — Web UI, Telegram, Discord, API access with synchronized responses
• Built-in Throttling — Per-IP endpoint limits with strict login protection
• Long-Term Memory — Embeddings-powered knowledge base with hybrid search
• Hook System — Observe, modify, or block actions at any lifecycle point
• Compile-Time Safety — Misconfigurations caught by cargo check, not runtime crashes

See the full list of supported providers.

Quick Start

# Install
curl -fsSL https://www.moltis.org/install.sh | sh

# Run
moltis

On first launch:

1. Open the URL shown in your browser (e.g., http://localhost:13131)
2. Add your LLM API key
3. Start chatting!

→ Full Quickstart Guide

How It Works

┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│  Web UI  │  │ Telegram │  │ Discord  │  │   API    │
└────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │             │
     └─────────────┴─────────┬───┴─────────────┘
                             │
                             ▼
        ┌───────────────────────────────┐
        │       Moltis Gateway          │
        │   ┌─────────┐ ┌───────────┐   │
        │   │  Agent  │ │   Tools   │   │
        │   │  Loop   │◄┤  Registry │   │
        │   └────┬────┘ └───────────┘   │
        │        │                      │
        │   ┌────▼────────────────┐     │
        │   │  Provider Registry  │     │
        │   │ Anthropic·OpenAI·Gemini… │   │
        │   └─────────────────────┘     │
        └───────────────────────────────┘
                        │
                ┌───────▼───────┐
                │    Sandbox    │
                │ Docker/Apple  │
                └───────────────┘

Documentation

Getting Started

• Quickstart — Up and running in 5 minutes
• Installation — All installation methods
• Configuration — moltis.toml reference
• End-to-End Testing — Browser regression coverage for the web UI

Features

• Providers — Configure LLM providers
• MCP Servers — Extend with Model Context Protocol
• Hooks — Lifecycle hooks for customization
• Local LLMs — Run models on your machine

Deployment

• Docker — Container deployment

Architecture

• Streaming — How real-time streaming works
• Metrics & Tracing — Observability

Security

Moltis applies defense in depth:

• Authentication — Password or passkey (WebAuthn) required for non-localhost access
• SSRF Protection — Blocks requests to internal networks
• Secret Handling — secrecy::Secret zeroes memory on drop
• Sandboxed Execution — Commands never run on the host
• Origin Validation — Prevents Cross-Site WebSocket Hijacking
• No Unsafe Code — unsafe is denied workspace-wide

Community

• GitHub: github.com/moltis-org/moltis
• Issues: Report bugs
• Discussions: Ask questions

License

MIT — Free for personal and commercial use.

Quickstart

Get Moltis running in under 5 minutes.

1. Install

curl -fsSL https://www.moltis.org/install.sh | sh

Or via Homebrew:

brew install moltis-org/tap/moltis

2. Start

moltis

You’ll see output like:

🚀 Moltis gateway starting...
🌐 Open http://localhost:13131 in your browser

3. Configure a Provider

You need an LLM provider configured to chat. The fastest options:

Option A: API Key (Anthropic, OpenAI, Gemini, etc.)

1. Set an API key as an environment variable and restart Moltis:

   export ANTHROPIC_API_KEY="sk-ant-..."   # Anthropic
   export OPENAI_API_KEY="sk-..."          # OpenAI
   export GEMINI_API_KEY="..."             # Google Gemini
   

2. Models appear automatically in the model picker.

Or configure via the web UI: Settings → Providers → enter your API key.

Option B: OAuth (Codex / Copilot)

1. In Moltis, go to Settings → Providers
2. Click OpenAI Codex or GitHub Copilot → Connect
3. Complete the OAuth flow

Option C: Local LLM (Offline)

1. In Moltis, go to Settings → Providers
2. Click Local LLM
3. Choose a model and save

See Providers for the full list of supported providers.

4. Chat!

Go to the Chat tab and start a conversation:

You: Write a Python function to check if a number is prime

Agent: Here's a Python function to check if a number is prime:

def is_prime(n):
    if n < 2:
        return False
    for i in range(2, int(n ** 0.5) + 1):
        if n % i == 0:
            return False
    return True

What’s Next?

Enable Tool Use

Moltis can execute code, browse the web, and more. Tools are enabled by default with sandbox protection.

Try:

You: Create a hello.py file that prints "Hello, World!" and run it

Connect Telegram

Chat with your agent from anywhere:

1. Create a bot via @BotFather
2. Copy the bot token
3. In Moltis: Settings → Telegram → Enter token → Save
4. Message your bot!

Connect Discord

1. Create a bot in the Discord Developer Portal
2. Enable Message Content Intent and copy the bot token
3. In Moltis: Settings → Channels → Connect Discord → Enter token → Connect
4. Invite the bot to your server and @mention it!

→ Full Discord setup guide

Add MCP Servers

Extend capabilities with MCP servers:

# In moltis.toml
[mcp]
[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_..." }

Set Up Memory

Enable long-term memory for context across sessions:

# In moltis.toml
[memory]
provider = "openai"
model = "text-embedding-3-small"

Add knowledge by placing Markdown files in ~/.moltis/memory/.

Useful Commands

File Locations

Getting Help

• Documentation: docs.moltis.org
• GitHub Issues: github.com/moltis-org/moltis/issues
• Discussions: github.com/moltis-org/moltis/discussions

Installation

Moltis is distributed as a single self-contained binary. Choose the installation method that works best for your setup.

Quick Install (Recommended)

The fastest way to get started on macOS or Linux:

curl -fsSL https://www.moltis.org/install.sh | sh

This downloads the latest release for your platform and installs it to ~/.local/bin.

Package Managers

Homebrew (macOS / Linux)

brew install moltis-org/tap/moltis

Linux Packages

Debian / Ubuntu (.deb)

# Download the latest .deb package
curl -LO https://github.com/moltis-org/moltis/releases/latest/download/moltis_amd64.deb

# Install
sudo dpkg -i moltis_amd64.deb

Fedora / RHEL (.rpm)

# Download the latest .rpm package
curl -LO https://github.com/moltis-org/moltis/releases/latest/download/moltis.x86_64.rpm

# Install
sudo rpm -i moltis.x86_64.rpm

Arch Linux (.pkg.tar.zst)

# Download the latest package
curl -LO https://github.com/moltis-org/moltis/releases/latest/download/moltis.pkg.tar.zst

# Install
sudo pacman -U moltis.pkg.tar.zst

Snap

sudo snap install moltis

AppImage

# Download
curl -LO https://github.com/moltis-org/moltis/releases/latest/download/moltis.AppImage
chmod +x moltis.AppImage

# Run
./moltis.AppImage

Docker

Multi-architecture images (amd64/arm64) are published to GitHub Container Registry:

docker pull ghcr.io/moltis-org/moltis:latest

See Docker Deployment for full instructions on running Moltis in a container.

Build from Source

Prerequisites

• Rust 1.91 or later
• A C compiler (for some dependencies)
• just (command runner)
• Node.js (for building Tailwind CSS)

Clone and Build

git clone https://github.com/moltis-org/moltis.git
cd moltis
just build-css           # Build Tailwind CSS for the web UI
just build-release       # Build in release mode

For a full release build including WASM sandbox tools:

just build-release-with-wasm

The binary will be at target/release/moltis.

Install via Cargo

cargo install moltis --git https://github.com/moltis-org/moltis

First Run

After installation, start Moltis:

moltis

On first launch:

1. Open http://localhost:<port> in your browser (the port is shown in the terminal output)
2. Configure your LLM provider (API key)
3. Start chatting!

Verify Installation

moltis --version

Updating

Homebrew

brew upgrade moltis

From Source

cd moltis
git pull
just build-css
just build-release

Uninstalling

Homebrew

brew uninstall moltis

Remove Data

Moltis stores data in two directories:

# Configuration
rm -rf ~/.config/moltis

# Data (sessions, databases, memory)
rm -rf ~/.moltis

Comparison

How Moltis compares to other open-source AI agent frameworks.

Disclaimer: This comparison reflects publicly available information at the time of writing. Projects evolve quickly — check each project’s repository for the latest details. Contributions to keep this page accurate are welcome.

At a Glance

* unsafe is denied workspace-wide in Moltis. The only exceptions are opt-in FFI wrappers behind the local-embeddings feature flag, not part of the core.

Architecture Approach

OpenClaw — Full-featured monolith

OpenClaw is the original and most popular project (~211K stars). It ships as a Node.js application with 52+ modules, 45+ npm dependencies, and a large surface area. It has the richest ecosystem of third-party skills and integrations, but the codebase is difficult to audit end-to-end.

PicoClaw — Minimal Go binary

PicoClaw targets extreme resource constraints — $10 SBCs, RISC-V boards, and devices with as little as 10 MB of RAM. It boots in under 1 second on 0.6 GHz hardware. The trade-off is a narrower feature set: no sandbox isolation, no built-in memory/RAG, and limited extensibility.

NanoClaw — Container-first TypeScript

NanoClaw strips away OpenClaw’s complexity to deliver a small, readable TypeScript codebase with first-class container isolation. Agents run in Linux containers with filesystem isolation. It uses Claude Agent SDK for sub-agent delegation and per-group CLAUDE.md memory files. The trade-off is Node.js as a runtime dependency and a smaller feature surface.

ZeroClaw — Lightweight Rust

ZeroClaw compiles to a tiny 3.4 MB binary with <5 MB RAM usage and sub-10ms startup. It uses trait-driven architecture with 22+ provider implementations and 9+ channel integrations. Memory is backed by SQLite with hybrid vector + FTS search. The focus is on minimal footprint and broad platform support.

Moltis — Auditable Rust gateway

Moltis prioritizes auditability and defense in depth. The core agent engine (runner + provider model) is ~5K lines; the core (excluding the optional web UI) is ~196K lines across 46 modular crates, each independently auditable. Key differences from ZeroClaw:

• Larger binary (44 MB) in exchange for built-in voice I/O, browser automation, web UI, and MCP support
• Apple Container support in addition to Docker
• WebAuthn passkey authentication — not just tokens
• 15 lifecycle hook events with circuit breaker and dry-run mode
• Built-in web UI with real-time streaming, settings management, and session branching

Security Model

Performance

Moltis is larger because it bundles a web UI, voice engine, browser automation, and MCP runtime. Use --no-default-features --features lightweight for constrained devices.

When to Choose What

Choose OpenClaw if you want the largest ecosystem, maximum third-party skills, and don’t mind Node.js as a dependency.

Choose PicoClaw if you need to run on extremely constrained hardware ($10 boards, RISC-V) and can accept a minimal feature set.

Choose NanoClaw if you want a small, readable TypeScript codebase with container isolation and don’t need voice, MCP, or a web UI.

Choose ZeroClaw if you want the smallest possible Rust binary, sub-10ms startup, and broad channel support without a web UI.

Choose Moltis if you want:

• A single auditable Rust binary with built-in web UI
• Voice I/O with 15+ providers (8 TTS + 7 STT)
• MCP server support (stdio + HTTP/SSE)
• WebAuthn passkey authentication
• Apple Container sandbox support (macOS native)
• 15 lifecycle hook events with circuit breaker
• Embeddings-powered long-term memory with hybrid search
• Cron scheduling, browser automation, and Tailscale integration

Links

• OpenClaw — Docs
• PicoClaw — Site
• NanoClaw
• ZeroClaw — Site
• Moltis — Docs

Configuration

Moltis is configured through moltis.toml, located in ~/.config/moltis/ by default.

On first run, a complete configuration file is generated with sensible defaults. You can edit it to customize behavior.

Configuration File Location

Basic Settings

[server]
port = 13131                    # HTTP/WebSocket port
bind = "0.0.0.0"               # Listen address

[identity]
name = "Moltis"                 # Agent display name

[tools]
agent_timeout_secs = 600        # Agent run timeout (seconds, 0 = no timeout)
agent_max_iterations = 25       # Max tool call iterations per run

LLM Providers

Configure providers through the web UI or directly in moltis.toml. API keys can be set via environment variables (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) or in the config file.

[providers]
offered = ["anthropic", "openai", "gemini"]

[providers.anthropic]
enabled = true

[providers.openai]
enabled = true
models = ["gpt-5.3", "gpt-5.2"]
stream_transport = "sse"        # "sse", "websocket", or "auto"

[providers.gemini]
enabled = true
models = ["gemini-2.5-flash-preview-05-20", "gemini-2.0-flash"]

[providers.local-llm]
enabled = true
models = ["qwen2.5-coder-7b-q4_k_m"]

[chat]
priority_models = ["gpt-5.2"]

See Providers for the full list of supported providers and configuration options.

Sandbox Configuration

Commands run inside isolated containers for security:

[tools.exec.sandbox]
mode = "all"                    # "off", "non-main", or "all"
scope = "session"               # "command", "session", or "global"
workspace_mount = "ro"          # "ro", "rw", or "none"
# host_data_dir = "/host/path/data"  # Optional override if auto-detection cannot resolve the host path
home_persistence = "shared"     # "off", "session", or "shared" (default: "shared")
# shared_home_dir = "/path/to/shared-home"  # Optional path for shared mode
backend = "auto"                # "auto", "docker", or "apple-container"
no_network = true

# Packages installed in the sandbox image
packages = [
    "curl",
    "git",
    "jq",
    "tmux",
    "python3",
    "python3-pip",
    "nodejs",
    "npm",
    "golang-go",
]

If Moltis runs inside Docker and also mounts the host container socket (/var/run/docker.sock), Moltis now auto-detects the host path backing /home/moltis/.moltis from the parent container’s mount table. If that inspection cannot resolve the correct path, set host_data_dir explicitly.

Web Search

Configure the built-in web_search tool:

[tools.web.search]
enabled = true
provider = "brave"               # "brave" or "perplexity"
max_results = 5                  # 1-10
timeout_seconds = 30
cache_ttl_minutes = 15
duckduckgo_fallback = false      # Default: do not use DuckDuckGo fallback
# api_key = "..."                # Brave key, or use BRAVE_API_KEY

[tools.web.search.perplexity]
# api_key = "..."                # Or use PERPLEXITY_API_KEY / OPENROUTER_API_KEY
# base_url = "..."               # Optional override
# model = "perplexity/sonar-pro" # Optional override

If no search API key is configured:

• with duckduckgo_fallback = false (default), Moltis returns a clear hint to set BRAVE_API_KEY or PERPLEXITY_API_KEY
• with duckduckgo_fallback = true, Moltis attempts DuckDuckGo HTML search, which may hit CAPTCHA/rate limits

Skills

Configure skill discovery and agent-managed personal skills:

[skills]
enabled = true
auto_load = ["commit"]
enable_agent_sidecar_files = false  # Opt-in: allow agents to write sidecar text files in personal skills

enable_agent_sidecar_files is disabled by default. When enabled, Moltis registers the write_skill_files tool so agents can write supplementary files such as script.sh, Dockerfile, templates, or _meta.json inside <data_dir>/skills/<name>/. Writes stay confined to that personal skill directory, reject path traversal and symlink escapes, and are recorded in ~/.moltis/logs/security-audit.jsonl.

Chat Message Queue

When a new message arrives while an agent run is already active, Moltis can either replay queued messages one-by-one or merge them into a single follow-up message.

[chat]
message_queue_mode = "followup"  # Default: one-by-one replay

# Options:
#   "followup" - Queue each message and run them sequentially
#   "collect"  - Merge queued text and run once after the active run

Memory System

Long-term memory uses embeddings for semantic search:

[memory]
backend = "builtin"             # Or "qmd"
provider = "openai"             # Or "local", "ollama", "custom"
model = "text-embedding-3-small"
citations = "auto"              # "on", "off", or "auto"
llm_reranking = false
session_export = false

Authentication

Authentication is only required when accessing Moltis from a non-localhost address. When running on localhost or 127.0.0.1, no authentication is needed by default.

When you access Moltis from a network address (e.g., http://192.168.1.100:13131), a one-time setup code is printed to the terminal. Use it to set up a password or passkey.

[auth]
disabled = false                # Set true to disable auth entirely

Hooks

Configure lifecycle hooks:

[hooks]
[[hooks.hooks]]
name = "my-hook"
command = "./hooks/my-hook.sh"
events = ["BeforeToolCall", "AfterToolCall"]
timeout = 5                     # Timeout in seconds

[hooks.hooks.env]
MY_VAR = "value"               # Environment variables for the hook

See Hooks for the full hook system documentation.

MCP Servers

Connect to Model Context Protocol servers:

[mcp]
request_timeout_secs = 30
                                    # Default timeout for MCP requests (seconds)

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
request_timeout_secs = 90        # Optional override for this server

[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_..." }

[mcp.servers.remote_api]
transport = "sse"
url = "https://mcp.example.com/mcp?api_key=$REMOTE_MCP_KEY"
headers = { Authorization = "Bearer ${REMOTE_MCP_TOKEN}" }

Remote MCP URLs and headers support $NAME or ${NAME} placeholders. For live remote servers, values resolve from Moltis-managed env overrides, either [env] in config or Settings → Environment Variables.

Telegram Integration

[channels.telegram.my-bot]
token = "123456:ABC..."
dm_policy = "allowlist"
allowlist = ["123456789"]       # Telegram user IDs or usernames (strings)

See Telegram for full configuration reference and setup instructions.

Discord Integration

[channels]
offered = ["telegram", "discord"]

[channels.discord.my-bot]
token = "MTIzNDU2Nzg5.example.bot-token"
dm_policy = "allowlist"
mention_mode = "mention"
allowlist = ["your_username"]

See Discord for full configuration reference and setup instructions.

Slack Integration

[channels]
offered = ["slack"]

[channels.slack.my-bot]
bot_token = "xoxb-..."
app_token = "xapp-..."
dm_policy = "allowlist"
allowlist = ["U123456789"]

See Slack for full configuration reference and setup instructions.

TLS / HTTPS

[tls]
enabled = true
cert_path = "~/.config/moltis/cert.pem"
key_path = "~/.config/moltis/key.pem"
# If paths don't exist, a self-signed certificate is generated

# Port for the plain-HTTP redirect / CA-download server.
# Defaults to the server port + 1 when not set.
# http_redirect_port = 13132

Override via environment variable: MOLTIS_TLS__HTTP_REDIRECT_PORT=8080.

Tailscale Integration

Expose Moltis over your Tailscale network:

[tailscale]
mode = "serve"                  # "off", "serve", or "funnel"
reset_on_exit = true

Observability

[metrics]
enabled = true
prometheus_endpoint = true

Process Environment Variables ([env])

The [env] section injects variables into the Moltis process at startup. This is useful in Docker deployments where passing individual -e flags is inconvenient, or when you want API keys stored in the config file rather than the host environment.

[env]
BRAVE_API_KEY = "your-brave-key"
OPENROUTER_API_KEY = "sk-or-..."
ELEVENLABS_API_KEY = "..."

Precedence: existing process environment variables are never overwritten. If BRAVE_API_KEY is already set via docker -e or the host shell, the [env] value is skipped. This means docker -e always wins.

Environment Variables

All settings can be overridden via environment variables:

CLI Flags

moltis --config-dir /path/to/config --data-dir /path/to/data

Complete Example

[server]
port = 13131
bind = "0.0.0.0"

[identity]
name = "Atlas"

[tools]
agent_timeout_secs = 600
agent_max_iterations = 25

[providers]
offered = ["anthropic", "openai", "gemini"]

[tools.exec.sandbox]
mode = "all"
scope = "session"
workspace_mount = "ro"
home_persistence = "session"
# shared_home_dir = "/path/to/shared-home"
backend = "auto"
no_network = true
packages = ["curl", "git", "jq", "python3", "nodejs", "golang-go"]

[memory]
backend = "builtin"
provider = "openai"
model = "text-embedding-3-small"

[auth]
disabled = false

[hooks]
[[hooks.hooks]]
name = "audit-log"
command = "./hooks/audit.sh"
events = ["BeforeToolCall"]
timeout = 5

Local Validation

Moltis provides a local validation script that runs the same checks as CI (format, lint, test, e2e), plus a native macOS app build check on macOS hosts.

Why this exists

• Faster feedback for Rust-heavy branches (no long runner queues for every push)
• Better parity with a developer’s local environment while iterating
• Clear visibility in the PR UI (fmt, biome, zizmor, clippy, test, macos-app, e2e)

Run local validation

Run all checks on your current checkout:

./scripts/local-validate.sh

When working on a pull request, pass the PR number to also publish commit statuses to GitHub:

./scripts/local-validate.sh 63

The script runs these checks:

• local/fmt
• local/biome
• local/zizmor
• local/lockfile — verifies Cargo.lock is in sync (cargo fetch --locked)
• local/lint
• local/test
• local/macos-app — validates the native Swift macOS app build (Darwin only)
• local/e2e — runs gateway UI Playwright coverage

In PR mode, the PR workflow verifies these contexts and surfaces them as checks in the PR.

Notes

• The script requires a clean working tree (no uncommitted or untracked changes). Commit or stash local changes before running.
• On macOS without CUDA (nvcc), the script automatically falls back to non-CUDA test/coverage defaults for local runs.
• On Linux, local/lint and local/test use --all-features. If you want the opt-in Vulkan path covered locally, install the Vulkan development packages first, for example libvulkan-dev and glslang-tools on Debian/Ubuntu (on Ubuntu 22.04, install glslc from the LunarG Vulkan SDK).
• local/lint uses the same clippy flags as CI and release: cargo +nightly-2025-11-30 clippy -Z unstable-options --workspace --all-features --all-targets --timings -- -D warnings.
• zizmor is installed automatically (Homebrew on macOS, apt on Linux) when not already available.
• zizmor is advisory in local runs and does not block lint/test execution.
• Test output is suppressed unless tests fail.
• local/macos-app runs only on macOS; on Linux it is marked skipped.
• Override or disable macOS app validation with: LOCAL_VALIDATE_MACOS_APP_CMD and LOCAL_VALIDATE_SKIP_MACOS_APP=1.
• local/e2e auto-runs npm ci only when crates/web/ui/node_modules is missing, then runs npm run e2e:install and npm run e2e. Override with LOCAL_VALIDATE_E2E_CMD.

Merge and release safety

This local-first flow is for pull requests. Full CI still runs on GitHub runners for non-PR events (for example push to main, scheduled runs, and release paths).

End-to-End Testing

This project uses Playwright to run browser-level tests against a real moltis gateway process.

The goal is simple: catch web UI regressions before they ship.

Why This Approach

• Tests run in a real browser (Chromium), not a DOM mock.
• Tests hit real gateway routes and WebSocket behavior.
• Runtime state is isolated so local machine config does not leak into test outcomes.

Current Setup

The e2e harness lives in crates/web/ui:

• playwright.config.js configures Playwright and web server startup.
• e2e/start-gateway.sh boots the gateway in deterministic test mode.
• e2e/specs/smoke.spec.js contains smoke coverage for critical routes.

How Startup Works

e2e/start-gateway.sh:

1. Creates isolated runtime directories under target/e2e-runtime.
2. Seeds IDENTITY.md and USER.md so onboarding does not block tests.
3. Exports MOLTIS_CONFIG_DIR, MOLTIS_DATA_DIR, and test port env.
4. Starts the gateway with:

cargo run --bin moltis -- --no-tls --bind 127.0.0.1 --port <PORT>

--no-tls is intentional here so Playwright can probe http://.../health during readiness checks.

Running E2E

From repo root (recommended):

just ui-e2e-install
just ui-e2e

Headed mode:

just ui-e2e-headed

Directly from crates/web/ui:

npm install
npm run e2e:install
npm run e2e

Test Artifacts

On failures, Playwright stores artifacts in:

• crates/web/ui/test-results/ (screenshots, video, traces)
• crates/web/ui/playwright-report/ (HTML report)

Open a trace with:

cd crates/web/ui
npx playwright show-trace test-results/<test-dir>/trace.zip

Writing Stable Tests

• Prefer stable IDs/selectors over broad text matching.
• Assert route + core UI state, avoid over-asserting cosmetic details.
• Keep smoke tests fast and deterministic.
• Add focused scenario tests for high-risk features (chat send flow, settings persistence, skills, projects, crons).

CI Integration

The just ui-e2e target is the intended command for CI.

Pull requests use the local-validation flow: the E2E workflow waits for a local/e2e commit status, published by ./scripts/local-validate.sh.

Pushes to main, tags, and manual dispatch still run the hosted E2E job.

LLM Providers

Moltis supports multiple LLM providers through a trait-based architecture. Configure providers through the web UI or directly in configuration files.

Available Providers

API Key Providers

OAuth Providers

Local

Custom OpenAI-Compatible

Any OpenAI-compatible endpoint can be added with a custom- prefix:

[providers.custom-myservice]
enabled = true
api_key = "..."
base_url = "https://my-service.example.com/v1"
models = ["my-model"]

Configuration

Via Web UI (Recommended)

1. Open Moltis in your browser.
2. Go to Settings → Providers.
3. Choose a provider card.
4. Complete OAuth or enter your API key.
5. Select your preferred model.

Via Configuration Files

Configure providers in moltis.toml:

[providers]
offered = ["anthropic", "openai", "gemini"]

[providers.anthropic]
enabled = true

[providers.openai]
enabled = true
models = ["gpt-5.3", "gpt-5.2"]
stream_transport = "sse"              # "sse", "websocket", or "auto"

[providers.gemini]
enabled = true
models = ["gemini-2.5-flash-preview-05-20", "gemini-2.0-flash"]
# api_key = "..."                     # Or set GEMINI_API_KEY / GOOGLE_API_KEY env var
# fetch_models = true                 # Discover models from the API
# base_url = "https://generativelanguage.googleapis.com/v1beta/openai"

[chat]
priority_models = ["gpt-5.2"]

Provider Entry Options

Each provider supports these options:

Provider Setup

Google Gemini

Google Gemini uses an API key from Google AI Studio.

1. Get an API key from Google AI Studio.
2. Set GEMINI_API_KEY in your environment (or use GOOGLE_API_KEY).
3. Gemini models appear automatically in the model picker.

[providers.gemini]
enabled = true
models = ["gemini-2.5-flash-preview-05-20", "gemini-2.0-flash"]

Gemini supports native tool calling, vision/multimodal inputs, streaming, and automatic model discovery.

Anthropic

1. Get an API key from console.anthropic.com.
2. Set ANTHROPIC_API_KEY in your environment.

OpenAI

1. Get an API key from platform.openai.com.
2. Set OPENAI_API_KEY in your environment.

OpenAI Codex

OpenAI Codex uses OAuth-based access.

1. Go to Settings → Providers → OpenAI Codex.
2. Click Connect and complete the auth flow.
3. Choose a Codex model.

If the browser cannot reach localhost:1455, Moltis now supports a manual fallback in both Settings and Onboarding: paste the callback URL (or code#state) into the OAuth panel and submit it.

# Docker
docker exec -it moltis moltis auth login --provider openai-codex

# Fly.io
fly ssh console -C "moltis auth login --provider openai-codex"

GitHub Copilot

GitHub Copilot uses OAuth authentication.

1. Go to Settings → Providers → GitHub Copilot.
2. Click Connect.
3. Complete the GitHub OAuth flow.

docker exec -it moltis moltis auth login --provider github-copilot

Ollama

Ollama auto-detects when running at http://127.0.0.1:11434. No API key needed.

[providers.ollama]
enabled = true
# base_url = "http://127.0.0.1:11434/v1"  # Override for remote Ollama

LM Studio

LM Studio auto-detects when running at http://127.0.0.1:1234. No API key needed. Also works with llama.cpp or any OpenAI-compatible local server.

[providers.lmstudio]
enabled = true
# base_url = "http://127.0.0.1:1234/v1"  # Override for different port/host

Local LLM

Local LLM runs GGUF models directly on your machine.

1. Go to Settings → Providers → Local LLM.
2. Choose a model from the local registry or download one.
3. Save and select it as your active model.

Switching Models

• Per session: Use the model selector in the chat UI.
• Per message: Use /model <name> in chat.
• Global defaults: Use [providers].offered, provider models = [...], and [chat].priority_models in moltis.toml.

Troubleshooting

“Model not available”

• Check provider auth is still valid.
• Check model ID spelling.
• Check account access for that model.

“Rate limited”

• Retry after a short delay.
• Switch provider/model.
• Upgrade provider quota if needed.

“Invalid API key”

• Verify the key has no extra spaces.
• Verify it is active and has required permissions.

Why Moltis Doesn’t Support Anthropic OAuth

A common request is browser-based OAuth login for Anthropic, similar to what Moltis offers for OpenAI Codex and GitHub Copilot. This page explains why that isn’t possible and what to do instead.

TL;DR

Anthropic does not offer an OAuth program for third-party tools. Their OAuth flow is locked to Claude Code and Claude.ai only. The only supported way to use Anthropic models in Moltis is with an API key from the Anthropic Console.

Background

Claude Code (Anthropic’s CLI) authenticates via an OAuth 2.0 PKCE flow against console.anthropic.com. The temporary OAuth token is then exchanged for a permanent API key through an internal endpoint (/api/oauth/claude_cli/create_api_key). The path segment /claude_cli/ signals this is a CLI-specific, internal endpoint — not a public API.

The client ID used by Claude Code (9d1c250a-…) is hard-coded for that single application. Anthropic does not provide a way to register new client IDs for third-party projects.

Anthropic’s Policy

In February 2026 Anthropic updated their Legal and Compliance page with an explicit restriction:

OAuth authentication (used with Free, Pro, and Max plans) is intended exclusively for Claude Code and Claude.ai. Using OAuth tokens obtained through Claude Free, Pro, or Max accounts in any other product, tool, or service — including the Agent SDK — is not permitted and constitutes a violation of the Consumer Terms of Service.

This isn’t just a policy statement — Anthropic deployed server-side enforcement in January 2026. OAuth tokens from consumer plans now return errors outside of Claude Code and Claude.ai:

“This credential is only authorized for use with Claude Code and cannot be used for other API requests.”

Several projects that attempted this approach — including Auto-Claude, Goose, and OpenCode — were forced to drop OAuth and switch to standard API keys.

What About Reusing the Claude Code Client ID?

Even if the OAuth flow and key creation technically succeed today, using Claude Code’s client ID from a different application:

• Violates the Consumer Terms of Service (Section 3.7 — no automated access through bots or scripts except via official API keys).
• Risks key revocation — Anthropic reserves the right to revoke credentials without prior notice.
• Could break at any time — the client ID and internal endpoints are not part of a public, stable API surface.

How to Use Anthropic in Moltis

1. Go to console.anthropic.com and create an account (or sign in).
2. Navigate to Settings → API Keys and create a new key.
3. In Moltis, go to Settings → Providers → Anthropic and paste the key.

Alternatively, set the ANTHROPIC_API_KEY environment variable or add it to your moltis.toml:

[providers.anthropic]
enabled = true
api_key = "sk-ant-api03-..."

This is the method Anthropic officially recommends for all third-party integrations.

Will This Change?

If Anthropic introduces a developer OAuth program with client ID registration in the future, Moltis will adopt it. The generic infrastructure for OAuth-to-API-key exchange already exists in the codebase (the api_key_endpoint field on OAuthConfig), so adding support would be straightforward.

References

• Anthropic API — Getting Started — official auth docs (API key only)
• The Register — Anthropic clarifies ban on third-party tool access
• HN — Anthropic officially bans subscription auth for third-party use
• Claude Code #28091 — Anthropic disabled OAuth tokens for third-party apps
• Auto-Claude #1871 — OAuth policy violation
• Goose #3647 — Anthropic OAuth for third-party users

MCP Servers

Moltis supports the Model Context Protocol (MCP) for connecting to external tool servers. MCP servers extend your agent’s capabilities without modifying Moltis itself.

What is MCP?

MCP is an open protocol that lets AI assistants connect to external tools and data sources. Think of MCP servers as plugins that provide:

• Tools — Functions the agent can call (e.g., search, file operations, API calls)
• Resources — Data the agent can read (e.g., files, database records)
• Prompts — Pre-defined prompt templates

Supported Transports

Adding an MCP Server

Via Web UI

1. Go to Settings → MCP Servers
2. Click Add Server
3. For remote Streamable HTTP servers, enter the server URL and any optional request headers
4. Click Save

After saving a remote server, Moltis only shows a sanitized URL plus header names/count in the UI and status views. Stored header values stay hidden.

Via Configuration

Add servers to moltis.toml:

[mcp]
request_timeout_secs = 30

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]

[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_..." }
request_timeout_secs = 90

[mcp.servers.remote_api]
transport = "sse"
url = "https://mcp.example.com/mcp?api_key=$REMOTE_MCP_KEY"
headers = { Authorization = "Bearer ${REMOTE_MCP_TOKEN}" }

Remote URLs and headers support $NAME and ${NAME} placeholders. For live remote servers, placeholder values resolve from Moltis-managed env overrides, either [env] in config or Settings → Environment Variables.

Popular MCP Servers

Official Servers

Community Servers

Explore more at mcp.so and GitHub MCP Servers.

Configuration Options

[mcp]
request_timeout_secs = 30       # Global default timeout for MCP requests

[mcp.servers.my_server]
command = "node"                # Required for stdio transport
args = ["server.js"]            # Optional arguments

# Optional environment variables
env = { API_KEY = "secret", DEBUG = "true" }

# Optional: per-server timeout override
request_timeout_secs = 90

# Optional: remote transport
transport = "sse"               # "stdio" (default) or "sse"
url = "https://mcp.example.com/mcp"  # Required when transport = "sse"
headers = { "x-api-key" = "$REMOTE_MCP_KEY" }  # Optional request headers

Request Timeouts

Moltis applies MCP request timeouts in two layers:

• mcp.request_timeout_secs sets the global default for every MCP server
• mcp.servers.<name>.request_timeout_secs optionally overrides that default for a specific server

This is useful when most local MCP servers respond quickly, but one remote SSE server or one expensive tool server needs a longer timeout.

[mcp]
request_timeout_secs = 30

[mcp.servers.remote_api]
transport = "sse"
url = "https://mcp.example.com/mcp"
request_timeout_secs = 120

In the web UI, the MCP settings page lets you edit both the global default timeout and the optional timeout override for each configured server.

Remote SSE Secrets and Placeholders

Remote MCP servers often expect API keys or bearer tokens in the URL query string or request headers. Moltis supports both patterns.

[mcp.servers.linear_remote]
transport = "sse"
url = "https://mcp.example.com/mcp?api_key=$REMOTE_MCP_KEY"
headers = {
  Authorization = "Bearer ${REMOTE_MCP_TOKEN}",
  "x-workspace" = "team-a",
}

• Use $NAME or ${NAME} placeholders in remote url and headers
• Placeholder values resolve from Moltis-managed env overrides, either [env] in config or Settings → Environment Variables
• UI and API status payloads only expose sanitized URLs plus header names/count, not raw header values
• Query-string secrets are redacted when Moltis displays a remote URL after save

Server Lifecycle

┌─────────────────────────────────────────────────────┐
│                   MCP Server                         │
│                                                      │
│  Start → Initialize → Ready → [Tool Calls] → Stop   │
│            │                       │                 │
│            ▼                       ▼                 │
│     Health Check ◄─────────── Heartbeat             │
│            │                       │                 │
│            ▼                       ▼                 │
│    Crash Detected ───────────► Restart              │
│                                    │                 │
│                              Backoff Wait            │
└─────────────────────────────────────────────────────┘

Health Monitoring

Moltis monitors MCP servers and automatically:

• Detects crashes via process exit
• Restarts with exponential backoff
• Disables after max restart attempts
• Re-enables after cooldown period

Using MCP Tools

Once connected, MCP tools appear alongside built-in tools. The agent can use them naturally:

User: Search GitHub for Rust async runtime projects

Agent: I'll search GitHub for you.
[Calling github.search_repositories with query="rust async runtime"]

Found 15 repositories:
1. tokio-rs/tokio - A runtime for writing reliable async applications
2. async-std/async-std - Async version of the Rust standard library
...

Creating an MCP Server

Simple Node.js Server

// server.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "hello",
    description: "Says hello",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name to greet" }
      },
      required: ["name"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "hello") {
    const name = request.params.arguments.name;
    return { content: [{ type: "text", text: `Hello, ${name}!` }] };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Configure in Moltis

[mcp.servers.my_server]
command = "node"
args = ["server.js"]

Debugging

Check Server Status

In the web UI, go to Settings → MCP Servers to see:

• Connection status (connected/disconnected/error)
• Available tools
• Sanitized remote URL and configured header names
• Recent errors

View Logs

MCP server stderr is captured in Moltis logs:

# View gateway logs
tail -f ~/.moltis/logs.jsonl | grep -i mcp

Test Locally

Run the server directly to debug:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node server.js

OAuth Authentication

Remote MCP servers can require OAuth 2.1 authentication. Moltis handles this automatically — when a server returns 401 Unauthorized, the OAuth flow starts without any manual configuration.

How It Works

1. Moltis connects to the remote MCP server
2. The server returns 401 Unauthorized with a WWW-Authenticate header
3. Moltis discovers the authorization server via RFC 9728 (Protected Resource Metadata)
4. Moltis performs dynamic client registration (RFC 7591)
5. A PKCE authorization code flow opens your browser for login
6. After login, tokens are stored and used for all subsequent requests

Client registrations and tokens are cached locally, so you only need to log in once per server.

Manual OAuth Configuration

If a server doesn’t support standard OAuth discovery, you can configure credentials manually:

[mcp.servers.private_api]
url = "https://mcp.example.com/mcp"
transport = "sse"

[mcp.servers.private_api.oauth]
client_id = "your-client-id"
auth_url = "https://auth.example.com/authorize"
token_url = "https://auth.example.com/token"
scopes = ["mcp:read", "mcp:write"]

Re-authentication

If your session expires or tokens are revoked, Moltis automatically re-authenticates on the next 401 response. You can also trigger re-authentication manually via the mcp.reauth RPC method.

Security Considerations

• Review server code before running
• Limit file access — use specific paths, not /
• Use environment variables for secrets
• Prefer placeholders in remote URLs and headers ($NAME / ${NAME}) instead of hardcoding secrets repeatedly
• Network isolation — run untrusted servers in containers

Troubleshooting

Server won’t start

• Check the command exists: which npx
• Verify the package: npx @modelcontextprotocol/server-filesystem --help
• Check for port conflicts

Tools not appearing

• Server may still be initializing (wait a few seconds)
• Check server logs for errors
• Verify the server implements tools/list

Server keeps restarting

• Check stderr for crash messages
• Increase max_restart_attempts for debugging
• Verify environment variables are set correctly

Memory System

Moltis provides a powerful memory system that enables the agent to recall past conversations, notes, and context across sessions. This document explains the available backends, features, and configuration options.

Backends

Moltis supports two memory backends:

Built-in Backend

The default backend uses SQLite for storage with FTS5 for keyword search and optional vector embeddings for semantic search. Key advantages:

• Zero external dependencies: Everything is embedded in the moltis binary
• Fallback chain: Automatically switches between embedding providers if one fails
• Batch embedding: Reduces OpenAI API costs by 50% for large sync operations
• Embedding cache: Avoids re-embedding unchanged content

QMD Backend

QMD is an optional external sidecar that provides enhanced search capabilities:

• BM25 keyword search: Fast, instant results (similar to Elasticsearch)
• Vector search: Semantic similarity using local GGUF models
• Hybrid search with LLM reranking: Combines both methods with an LLM pass for optimal relevance

To use QMD:

1. Install the QMD CLI from github.com/tobi/qmd: npm install -g --ignore-scripts @tobilu/qmd or bun add -g @tobilu/qmd
2. Verify the binary is on your PATH: qmd --version
3. Enable it in Settings > Memory > Backend

Moltis invokes the qmd CLI directly for indexing and search, so the memory backend does not require a separate background daemon.

Features

Citations

Citations append source file and line number information to search results:

Some important content from your notes.

Source: memory/notes.md#42

Configuration options:

• auto (default): Include citations when results come from multiple files
• on: Always include citations
• off: Never include citations

Session Export

When enabled, session transcripts are automatically exported to the memory system for cross-run recall. This allows the agent to remember past conversations even after restarts.

Exported sessions are:

• Stored in memory/sessions/ as markdown files
• Sanitized to remove sensitive tool results and system messages
• Automatically cleaned up based on age/count limits

LLM Reranking

LLM reranking uses the configured language model to re-score and reorder search results based on semantic relevance to the query. This provides better results than keyword or vector matching alone, at the cost of additional latency.

How it works:

1. Initial search returns candidate results
2. LLM evaluates each result’s relevance (0.0-1.0 score)
3. Results are reordered by combined score (70% LLM, 30% original)

Configuration

Memory settings can be configured in moltis.toml:

[memory]
# Backend: "builtin" (default) or "qmd"
backend = "builtin"

# Embedding provider: "local", "ollama", "openai", "custom", or auto-detect
provider = "local"

# Disable RAG embeddings and force keyword-only search
disable_rag = false

# Embedding API base URL (host, /v1, or full /embeddings endpoint)
base_url = "http://localhost:11434/v1"

# Citation mode: "on", "off", or "auto"
citations = "auto"

# Enable LLM reranking for hybrid search
llm_reranking = false

# Export sessions to memory for cross-run recall
session_export = true

# QMD-specific settings (only used when backend = "qmd")
[memory.qmd]
command = "qmd"
max_results = 10
timeout_ms = 30000

Or via the web UI: Settings > Memory

Embedding Providers

The built-in backend supports multiple embedding providers:

The system auto-detects available providers and creates a fallback chain:

1. Try configured provider first
2. Fall back to other available providers if it fails
3. Use keyword-only search if no embedding provider is available

Memory Directories

By default, moltis indexes markdown files from:

• ~/.moltis/MEMORY.md - Main long-term memory file
• ~/.moltis/memory/*.md - Additional memory files
• ~/.moltis/memory/sessions/*.md - Exported session transcripts

Tools

The memory system exposes three agent tools:

memory_search

Search memory with a natural language query. Returns relevant chunks ranked by hybrid (vector + keyword) similarity.

{
  "query": "what did we discuss about the API design?",
  "limit": 5
}

memory_get

Retrieve a specific memory chunk by ID. Useful for reading the full text of a result found via memory_search.

{
  "chunk_id": "memory/notes.md:42"
}

memory_save

Save content to long-term memory files. The agent uses this tool when you ask it to remember something (“remember that I prefer dark mode”) or when it decides certain information is worth persisting.

{
  "content": "User prefers dark mode and Vim keybindings.",
  "file": "MEMORY.md",
  "append": true
}

Parameters:

Path validation: The tool enforces a strict allowlist of write targets to prevent path traversal attacks. Only these patterns are accepted:

• MEMORY.md or memory.md (root memory files)
• memory/<name>.md (files in the memory subdirectory, one level deep)

Absolute paths, .. traversal, non-.md extensions, spaces in filenames, and nested subdirectories (memory/a/b.md) are all rejected. Content is limited to 50 KB per write.

Auto-reindex: After writing, the memory system automatically re-indexes the affected file so the new content is immediately searchable via memory_search.

Silent Memory Turn (Pre-Compaction Flush)

Before compacting a session (summarizing old messages to free context window space), Moltis runs a silent agentic turn that reviews the conversation and saves important information to memory files. This ensures durable memories survive compaction.

How it works:

1. When a session approaches the model’s context window limit, the gateway triggers compaction
2. Before summarizing, a hidden LLM turn runs with a special system prompt asking the agent to save noteworthy information
3. The agent writes to MEMORY.md and/or memory/YYYY-MM-DD.md using an internal write_file tool backed by the same MemoryWriter as memory_save
4. The LLM’s response text is discarded (the user sees nothing)
5. Written files are automatically re-indexed for future search

What gets saved:

• User preferences and working style
• Key decisions and their reasoning
• Project context, architecture choices, and conventions
• Important facts, names, dates, and relationships
• Technical setup details (tools, languages, frameworks)

This is the same approach used by OpenClaw. See the comparison page for a detailed analysis of both systems.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                       Memory Manager                             │
│               (implements MemoryWriter trait)                     │
├──────────────────────────────────────────────────────────────────┤
│                         Read Path                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐      │
│  │   Chunker   │  │   Search    │  │  Session Export     │      │
│  │ (markdown)  │  │  (hybrid)   │  │  (transcripts)      │      │
│  └─────────────┘  └─────────────┘  └─────────────────────┘      │
├──────────────────────────────────────────────────────────────────┤
│                        Write Path                                │
│  ┌─────────────────┐  ┌──────────────────┐  ┌────────────────┐  │
│  │  memory_save    │  │  Silent Turn     │  │  Path          │  │
│  │  (agent tool)   │  │  (pre-compact)   │  │  Validation    │  │
│  └─────────────────┘  └──────────────────┘  └────────────────┘  │
├──────────────────────────────────────────────────────────────────┤
│                      Storage Backend                             │
│  ┌────────────────────────┐  ┌────────────────────────┐         │
│  │   Built-in (SQLite)    │  │   QMD (sidecar)        │         │
│  │  - FTS5 keyword        │  │  - BM25 keyword        │         │
│  │  - Vector similarity   │  │  - Vector similarity   │         │
│  │  - Embedding cache     │  │  - LLM reranking       │         │
│  └────────────────────────┘  └────────────────────────┘         │
├──────────────────────────────────────────────────────────────────┤
│                    Embedding Providers                            │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌───────────────┐      │
│  │  Local  │  │ Ollama  │  │ OpenAI  │  │ Batch/Fallback│      │
│  │  (GGUF) │  │         │  │         │  │               │      │
│  └─────────┘  └─────────┘  └─────────┘  └───────────────┘      │
└──────────────────────────────────────────────────────────────────┘

Troubleshooting

Memory not working

1. Check status in Settings > Memory
2. Ensure at least one embedding provider is available:
   • Local: Requires local-embeddings feature enabled at build
   • Ollama: Must be running at localhost:11434
   • OpenAI: Requires OPENAI_API_KEY environment variable

Search returns no results

1. Check that memory files exist in the expected directories
2. Trigger a manual sync by restarting moltis
3. Check logs for sync errors

QMD not available

1. Install QMD if needed: npm install -g --ignore-scripts @tobilu/qmd or bun add -g @tobilu/qmd
2. Verify QMD is installed: qmd --version
3. Check that the path is correct in settings
4. Ensure QMD has indexed your collections: qmd stats

Memory: Moltis vs OpenClaw

This page provides a detailed comparison of the memory systems in Moltis and OpenClaw. Both projects share the same core architecture for long-term memory, but differ in implementation details, tool surface, and configuration.

Overview

Both systems follow the same fundamental approach: plain Markdown files are the source of truth for agent memory, indexed for semantic search using hybrid vector + keyword retrieval. The agent reads from memory via search tools and writes to memory via file-writing tools (either dedicated or general-purpose).

Feature Comparison

Storage and Indexing

Embedding Providers

Memory Files

Agent Tools

This is where the two systems differ most significantly in approach.

How “Remember X” Works

When a user says “remember that I prefer dark mode”, here is how each system handles it:

Moltis: The agent calls the memory_save tool directly:

{
  "content": "User prefers dark mode.",
  "file": "MEMORY.md",
  "append": true
}

The memory_save tool validates the path, writes the file, and re-indexes it so the content is immediately searchable. The agent does not need shell access or a generic file-writing tool.

OpenClaw: The agent calls the generic write_file tool (which is also used for writing code, configs, and any other file):

{
  "path": "MEMORY.md",
  "content": "User prefers dark mode.",
  "append": true
}

The system prompt instructs the agent which paths are for memory. The tool itself has no special memory awareness – it is a general-purpose file writer. The memory indexer’s file watcher detects the change and re-indexes asynchronously (1.5s debounce).

Key difference: Moltis uses a purpose-built memory_save tool with built-in path validation (only MEMORY.md and memory/*.md are writable) and immediate re-indexing. OpenClaw uses a general-purpose write_file tool that can write anywhere, relying on the system prompt to guide the agent to memory paths and the file watcher to re-index.

Session Memory and Compaction

Pre-Compaction Memory Flush: Detailed Comparison

Both systems run a hidden LLM turn before compaction to persist important context. The implementation differs:

Moltis:

• The gateway detects that compaction is needed
• A run_silent_memory_turn() call creates a temporary agent loop with a write_file tool backed by MemoryWriter
• The MemoryWriter trait is implemented by MemoryManager, which validates paths and re-indexes after writing
• The LLM’s response text is discarded
• Written file paths are returned to the caller for logging

OpenClaw:

• A soft threshold (default 4000 tokens below compaction trigger) activates the flush
• The flush executes as a regular turn with NO_REPLY prefix to suppress user-facing output
• The agent writes memory files via the same write_file tool used during normal conversation
• Flush state is tracked in sessions.json (memoryFlushAt, memoryFlushCompactionCount) to run once per compaction cycle
• Skipped for read-only workspaces

Write Path Security

Search Features

Configuration

CLI Commands

Architecture

What Moltis Has That OpenClaw Does Not

• Dedicated memory_save tool with path validation and immediate re-indexing, reducing reliance on the system prompt for write guidance
• Ollama embedding support as a provider option
• Custom OpenAI-compatible embedding endpoints
• Circuit breaker with automatic fallback chain for embedding providers
• Web UI for memory configuration (Settings > Memory page)
• Pure Rust implementation with zero external runtime dependencies

What OpenClaw Has That Moltis Does Not (Yet)

• Manual /compact command with user-specified instructions
• CLI memory commands (status, index, search) for debugging
• Session pruning (cache-TTL based trimming of old tool results)
• Gemini and Voyage embedding providers
• Per-agent memory isolation for multi-agent setups
• Automatic re-indexing on embedding provider/model change (fingerprint detection)
• Memory plugin slot allowing third-party memory implementations
• Flush-once-per-compaction tracking to avoid redundant silent turns
• Configurable flush threshold (soft threshold tokens before compaction)

Summary

The two systems are architecturally equivalent – both use Markdown files, hybrid search, and pre-compaction memory flushes. The main differences are:

1. Tool approach: Moltis provides a purpose-built memory_save tool with security validation; OpenClaw uses a general-purpose write_file tool guided by the system prompt.

2. Write safety: Moltis validates write paths at the tool level (allowlist

   • traversal checks); OpenClaw relies on workspace-level access control.

3. Implementation: Moltis is pure Rust with a MemoryWriter trait abstraction; OpenClaw is TypeScript with direct file I/O through a plugin system.

4. Maturity: OpenClaw has more CLI tooling and configuration knobs for advanced memory management; Moltis has a simpler, more opinionated setup with a web UI.

Hooks

Hooks let you observe, modify, or block actions at key points in the agent lifecycle. Use them for auditing, policy enforcement, prompt injection filtering, notifications, and custom integrations.

How Hooks Work

┌──────────────────────────────────────────────────────────────┐
│                        Agent Loop                            │
│                                                              │
│  User Message ─→ BeforeLLMCall ─→ LLM Provider              │
│                       │                 │                    │
│                  modify/block      AfterLLMCall              │
│                                         │                    │
│                                    modify/block              │
│                                         │                    │
│                                         ▼                    │
│                                  BeforeToolCall              │
│                                         │                    │
│                                    modify/block              │
│                                         │                    │
│                                    Tool Execution            │
│                                         │                    │
│                                    AfterToolCall             │
│                                         │                    │
│                                         ▼                    │
│                              (loop continues or)             │
│                             Response → MessageSent           │
└──────────────────────────────────────────────────────────────┘

Event Types

Modifying Events (Sequential)

These events run hooks sequentially. Hooks can modify the payload or block the action.

Read-Only Events (Parallel)

These events run hooks in parallel for performance. They cannot modify or block.

Prompt Injection Filtering

The BeforeLLMCall and AfterLLMCall hooks provide filtering points for prompt injection defense.

BeforeLLMCall

Fires before each LLM API call. The payload includes the full message array, provider name, model ID, and iteration count. Use it to:

• Scan prompts for injection patterns before they reach the LLM
• Redact PII or sensitive data from the conversation
• Add safety prefixes to system prompts
• Block requests that match known attack patterns

Payload fields:

AfterLLMCall

Fires after the LLM response is received but before tool calls execute. For streaming responses, this fires after the full response is accumulated (text has already been streamed to the UI) but blocking still prevents tool execution.

Payload fields:

Example: Block Suspicious Tool Calls

#!/bin/bash
# filter-injection.sh — subscribe to AfterLLMCall
payload=$(cat)
event=$(echo "$payload" | jq -r '.event')

if [ "$event" = "AfterLLMCall" ]; then
    # Check if tool calls contain suspicious patterns
    tool_names=$(echo "$payload" | jq -r '.tool_calls[].name')

    for name in $tool_names; do
        # Block unexpected tool calls that might come from injection
        case "$name" in
            exec|bash|shell)
                text=$(echo "$payload" | jq -r '.text // ""')
                if echo "$text" | grep -qi "ignore previous\|disregard\|new instructions"; then
                    echo "Blocked suspicious tool call after potential injection" >&2
                    exit 1
                fi
                ;;
        esac
    done
fi

exit 0

Example: External Proxy Filter

#!/bin/bash
# proxy-filter.sh — subscribe to BeforeLLMCall
payload=$(cat)

# Send to an external moderation API
result=$(echo "$payload" | curl -s -X POST \
  -H "Content-Type: application/json" \
  -d @- \
  "$MODERATION_API_URL/check")

# Block if the API flags it
if echo "$result" | jq -e '.flagged' > /dev/null 2>&1; then
    reason=$(echo "$result" | jq -r '.reason // "content policy violation"')
    echo "$reason" >&2
    exit 1
fi

exit 0

Creating a Hook

1. Create the Hook Directory

mkdir -p ~/.moltis/hooks/my-hook

2. Create HOOK.md

+++
name = "my-hook"
description = "Logs all tool calls to a file"
events = ["BeforeToolCall", "AfterToolCall"]
command = "./handler.sh"
timeout = 5

[requires]
os = ["darwin", "linux"]
bins = ["jq"]
env = ["LOG_FILE"]
+++

# My Hook

This hook logs all tool calls for auditing purposes.

3. Create the Handler Script

#!/bin/bash
# handler.sh

# Read event payload from stdin
payload=$(cat)

# Extract event type
event=$(echo "$payload" | jq -r '.event')

# Log to file
echo "$(date -Iseconds) $event: $payload" >> "$LOG_FILE"

# Exit 0 to continue (don't block)
exit 0

4. Make it Executable

chmod +x ~/.moltis/hooks/my-hook/handler.sh

Shell Hook Protocol

Hooks communicate via stdin/stdout and exit codes:

Input

The event payload is passed as JSON on stdin:

{
  "event": "BeforeToolCall",
  "data": {
    "tool": "bash",
    "arguments": {
      "command": "ls -la"
    }
  },
  "session_id": "abc123",
  "timestamp": "2024-01-15T10:30:00Z"
}

Output

Example: Modify Tool Arguments

#!/bin/bash
payload=$(cat)
tool=$(echo "$payload" | jq -r '.data.tool')

if [ "$tool" = "bash" ]; then
    # Add safety flag to all bash commands
    modified=$(echo "$payload" | jq '.data.arguments.command = "set -e; " + .data.arguments.command')
    echo "{\"action\":\"modify\",\"data\":$(echo "$modified" | jq '.data')}"
fi

exit 0

Example: Block Dangerous Commands

#!/bin/bash
payload=$(cat)
command=$(echo "$payload" | jq -r '.data.arguments.command // ""')

# Block rm -rf /
if echo "$command" | grep -qE 'rm\s+-rf\s+/'; then
    echo "Blocked dangerous rm command" >&2
    exit 1
fi

exit 0

Hook Discovery

Hooks are discovered from HOOK.md files in these locations (priority order):

1. Project-local: <workspace>/.moltis/hooks/<name>/HOOK.md
2. User-global: ~/.moltis/hooks/<name>/HOOK.md

Project-local hooks take precedence over global hooks with the same name.

Configuration in moltis.toml

You can also define hooks directly in the config file:

[hooks]
[[hooks.hooks]]
name = "audit-log"
command = "./hooks/audit.sh"
events = ["BeforeToolCall", "AfterToolCall"]
timeout = 5

[[hooks.hooks]]
name = "llm-filter"
command = "./hooks/filter-injection.sh"
events = ["BeforeLLMCall", "AfterLLMCall"]
timeout = 10

[[hooks.hooks]]
name = "notify-slack"
command = "./hooks/slack-notify.sh"
events = ["SessionEnd"]
env = { SLACK_WEBHOOK_URL = "https://hooks.slack.com/..." }

Eligibility Requirements

Hooks can declare requirements that must be met:

[requires]
os = ["darwin", "linux"]       # Only run on these OSes
bins = ["jq", "curl"]          # Required binaries in PATH
env = ["SLACK_WEBHOOK_URL"]    # Required environment variables

If requirements aren’t met, the hook is skipped (not an error).

Circuit Breaker

Hooks that fail repeatedly are automatically disabled:

• Threshold: 5 consecutive failures
• Cooldown: 60 seconds
• Recovery: Auto-re-enabled after cooldown

This prevents a broken hook from blocking all operations.

CLI Commands

# List all discovered hooks
moltis hooks list

# List only eligible hooks (requirements met)
moltis hooks list --eligible

# Output as JSON
moltis hooks list --json

# Show details for a specific hook
moltis hooks info my-hook

Bundled Hooks

Moltis includes several built-in hooks:

boot-md

Reads BOOT.md from the workspace on GatewayStart and injects it into the agent context.

BOOT.md is intended for short, explicit startup tasks (health checks, reminders, “send one startup message”, etc.). If the file is missing or empty, nothing is injected.

Workspace Context Files

Moltis supports several workspace markdown files in data_dir.

TOOLS.md

TOOLS.md is loaded as a workspace context file in the system prompt.

Best use is to combine:

• Local notes: environment-specific facts (hosts, device names, channel aliases)
• Policy constraints: “prefer read-only tools first”, “never run X on startup”, etc.

If TOOLS.md is empty or missing, it is not injected.

AGENTS.md (workspace)

Moltis also supports a workspace-level AGENTS.md in data_dir.

This is separate from project AGENTS.md/CLAUDE.md discovery. Use workspace AGENTS.md for global instructions that should apply across projects in this workspace.

session-memory

Saves session context when you use the /new command, preserving important information for future sessions.

command-logger

Logs all Command events to a JSONL file for auditing.

Example Hooks

Recommended: Destructive Command Guard (dcg)

dcg is an external tool that scans shell commands against 49+ destructive pattern categories, including heredoc/inline-script scanning, database, cloud, and infrastructure patterns.

Install:

cargo install dcg

Hook setup:

Copy the bundled hook example to your hooks directory:

cp -r examples/hooks/dcg-guard ~/.moltis/hooks/dcg-guard
chmod +x ~/.moltis/hooks/dcg-guard/handler.sh

The hook subscribes to BeforeToolCall, extracts exec commands, pipes them through dcg, and blocks any command that dcg flags as destructive. See examples/hooks/dcg-guard/HOOK.md for details.

Note: dcg complements but does not replace the built-in dangerous command blocklist, sandbox isolation, or the approval system. Use it as an additional defense layer with broader pattern coverage.

Slack Notification on Session End

#!/bin/bash
# slack-notify.sh
payload=$(cat)
session_id=$(echo "$payload" | jq -r '.session_id')
message_count=$(echo "$payload" | jq -r '.data.message_count')

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{\"text\":\"Session $session_id ended with $message_count messages\"}"

exit 0

Redact Secrets from Tool Output

#!/bin/bash
# redact-secrets.sh
payload=$(cat)

# Redact common secret patterns
redacted=$(echo "$payload" | sed -E '
  s/sk-[a-zA-Z0-9]{32,}/[REDACTED]/g
  s/ghp_[a-zA-Z0-9]{36}/[REDACTED]/g
  s/password=[^&\s]+/password=[REDACTED]/g
')

echo "{\"action\":\"modify\",\"data\":$(echo "$redacted" | jq '.data')}"
exit 0

Block File Writes Outside Project

#!/bin/bash
# sandbox-writes.sh
payload=$(cat)
tool=$(echo "$payload" | jq -r '.data.tool')

if [ "$tool" = "write_file" ]; then
    path=$(echo "$payload" | jq -r '.data.arguments.path')

    # Only allow writes under current project
    if [[ ! "$path" =~ ^/workspace/ ]]; then
        echo "File writes only allowed in /workspace" >&2
        exit 1
    fi
fi

exit 0

Best Practices

1. Keep hooks fast — Set appropriate timeouts (default: 5s)
2. Handle errors gracefully — Use exit 0 unless you want to block
3. Log for debugging — Write to a log file, not stdout
4. Test locally first — Pipe sample JSON through your script
5. Use jq for JSON — It’s reliable and fast for parsing
6. Layer defenses — Use BeforeLLMCall for input filtering and AfterLLMCall for output filtering

Local LLM Support

Moltis can run LLM inference locally on your machine without requiring an API key or internet connection. This enables fully offline operation and keeps your conversations private.

Backends

Moltis supports two backends for local inference:

GGUF (llama.cpp)

GGUF is the primary backend, powered by llama.cpp. It supports quantized models in the GGUF format, which significantly reduces memory requirements while maintaining good quality.

Advantages:

• Cross-platform (macOS, Linux, Windows)
• Wide model compatibility (any GGUF model)
• GPU acceleration on Apple Silicon (Metal), NVIDIA (CUDA), and Vulkan-capable GPUs
• Mature and well-tested

MLX

MLX is Apple’s machine learning framework optimized for Apple Silicon. Models from the mlx-community on HuggingFace are specifically optimized for M1/M2/M3/M4 chips.

Advantages:

• Native Apple Silicon performance
• Efficient unified memory usage
• Lower latency on Macs

Requirements:

• macOS with Apple Silicon (M1/M2/M3/M4)

Memory Requirements

Models are organized by memory tiers based on your system RAM:

Moltis automatically detects your system memory and suggests appropriate models in the UI.

Configuration

Via Web UI (Recommended)

1. Navigate to Providers in the sidebar
2. Click Add Provider
3. Select Local LLM
4. Choose a model from the registry or search HuggingFace
5. Click Configure — the model will download automatically

Via Configuration File

Add to ~/.config/moltis/moltis.toml:

[providers.local-llm]
models = ["qwen2.5-coder-7b-q4_k_m"]

For custom GGUF files:

{
  "models": [
    {
      "model_id": "my-custom-model",
      "model_path": "/path/to/model.gguf",
      "gpu_layers": 99,
      "backend": "GGUF"
    }
  ]
}

Save this as ~/.config/moltis/local-llm.json (the same file managed by the Settings UI).

Model Storage

Downloaded models are cached in ~/.moltis/models/ by default. This directory can grow large (several GB per model).

HuggingFace Integration

You can search and download models directly from HuggingFace:

1. In the Add Provider dialog, click “Search HuggingFace”
2. Enter a search term (e.g., “qwen coder”)
3. Select GGUF or MLX backend
4. Choose a model from the results
5. The model will download immediately after you configure it

Finding GGUF Models

Look for repositories with “GGUF” in the name on HuggingFace:

• TheBloke — large collection of quantized models
• bartowski — Llama 3.x GGUF models
• Qwen — official Qwen GGUF models

Finding MLX Models

MLX models are available from mlx-community:

• Pre-converted models optimized for Apple Silicon
• Look for models ending in -4bit or -8bit for quantized versions

GPU Acceleration

Metal (macOS)

Metal acceleration is enabled by default on macOS. The number of GPU layers can be configured:

{
  "models": [
    {
      "model_id": "qwen2.5-coder-7b-q4_k_m",
      "gpu_layers": 99,
      "backend": "GGUF"
    }
  ]
}

CUDA (NVIDIA)

Requires building with the local-llm-cuda feature:

cargo build --release --features local-llm-cuda

Vulkan

Vulkan acceleration is available as an opt-in build. It is not enabled by default in Moltis release builds.

Build with:

cargo build --release --features local-llm-vulkan

Requirements:

• Linux: install Vulkan development packages, for example on Debian/Ubuntu: sudo apt-get install libvulkan-dev glslang-tools (Ubuntu 24.04+ also has a glslc package; on 22.04 install it from the LunarG Vulkan SDK if the build requires the glslc binary)
• Windows: install the LunarG Vulkan SDK and set the VULKAN_SDK environment variable before building

If llama.cpp detects a Vulkan device at runtime, Moltis will report GGUF as using Vulkan acceleration in the local model setup flow.

Limitations

Local LLM models have some limitations compared to cloud providers:

1. No tool calling — Local models don’t support function/tool calling. When using a local model, features like file operations, shell commands, and memory search are disabled.

2. Slower inference — Depending on your hardware, local inference may be significantly slower than cloud APIs.

3. Quality varies — Smaller quantized models may produce lower quality responses than larger cloud models.

4. Context window — Local models typically have smaller context windows (8K-32K tokens vs 128K+ for cloud models).

Chat Templates

Different model families use different chat formatting. Moltis automatically detects the correct template for registered models:

• ChatML — Qwen, many instruction-tuned models
• Llama 3 — Meta’s Llama 3.x family
• DeepSeek — DeepSeek Coder models

For custom models, the template is auto-detected from the model metadata when possible.

Troubleshooting

Model fails to load

• Check you have enough RAM (see memory tier table above)
• Verify the GGUF file isn’t corrupted (re-download if needed)
• Ensure the model file matches the expected architecture

Slow inference

• Enable GPU acceleration (Metal on macOS, CUDA on Linux)
• Try a smaller/more quantized model
• Reduce prompt/context length

Out of memory

• Choose a model from a lower memory tier
• Close other applications to free RAM
• Use a more aggressively quantized model (Q4_K_M vs Q8_0)

Feature Flag

Local LLM support requires the local-llm feature flag at compile time:

cargo build --release --features local-llm

This is enabled by default in release builds.

Sandbox Backends

Moltis runs LLM-generated commands inside containers to protect your host system. The sandbox backend controls which container technology is used.

Backend Selection

Configure in moltis.toml:

[tools.exec.sandbox]
backend = "auto"          # default — picks the best available
# backend = "podman"      # force Podman (daemonless, rootless)
# backend = "docker"      # force Docker
# backend = "apple-container"  # force Apple Container (macOS only)
# backend = "wasm"        # force WASM sandbox (Wasmtime + WASI)
# backend = "restricted-host"  # env clearing + rlimits only

With "auto" (the default), Moltis picks the strongest available backend:

The WASM backend (backend = "wasm") is not in the auto-detect chain because it cannot execute arbitrary shell commands — use it explicitly when you want WASI-isolated execution.

Apple Container (recommended on macOS)

Apple Container runs each sandbox in a lightweight virtual machine using Apple’s Virtualization.framework. Every container gets its own kernel, so a kernel exploit inside the sandbox cannot reach the host — unlike Docker, which shares the host kernel.

Install

Download the signed installer from GitHub:

# Download the installer package
gh release download --repo apple/container --pattern "container-installer-signed.pkg" --dir /tmp

# Install (requires admin)
sudo installer -pkg /tmp/container-installer-signed.pkg -target /

# First-time setup — downloads a default Linux kernel
container system start

Alternatively, build from source with brew install container (requires Xcode 26+).

Verify

container --version
# Run a quick test
container run --rm ubuntu echo "hello from VM"

Once installed, restart moltis gateway — the startup banner will show sandbox: apple-container backend.

Podman

Podman is a daemonless, rootless container engine that is CLI-compatible with Docker. It is preferred over Docker in auto-detection because it doesn’t require a background daemon process and runs rootless by default for better security.

Install

# macOS
brew install podman
podman machine init && podman machine start

# Debian/Ubuntu
sudo apt-get install -y podman

# Fedora/RHEL
sudo dnf install -y podman

Verify

podman --version
podman run --rm docker.io/library/ubuntu echo "hello from podman"

Once installed, restart moltis gateway — the startup banner will show sandbox: podman backend. All Docker hardening flags (see below) apply identically to Podman containers.

Docker

Docker is supported on macOS, Linux, and Windows. On macOS it runs inside a Linux VM managed by Docker Desktop, so it is reasonably isolated but adds more overhead than Apple Container.

Install from https://docs.docker.com/get-docker/

Docker/Podman Hardening

Docker and Podman containers launched by Moltis include the following security hardening flags by default:

The --read-only flag is applied only to prebuilt sandbox images (where packages are already baked in). Non-prebuilt images need a writable root filesystem for apt-get provisioning on first start.

WASM Sandbox (Wasmtime + WASI)

The WASM sandbox provides real sandboxed execution using Wasmtime with WASI. Commands execute in an isolated filesystem tree with fuel metering and epoch-based timeout enforcement.

How It Works

The WASM sandbox has two execution tiers:

Tier 1 — Built-in commands (~20 common coreutils implemented in Rust): echo, cat, ls, mkdir, rm, cp, mv, pwd, env, head, tail, wc, sort, touch, which, true, false, test/[, basename, dirname.

These operate on a sandboxed directory tree, translating guest paths (e.g. /home/sandbox/file.txt) to host paths under ~/.moltis/sandbox/wasm/<id>/. Paths outside the sandbox root are rejected.

Basic shell features are supported: &&, ||, ; sequences, $VAR expansion, quoting via shell-words, and > / >> output redirects.

Tier 2 — Real WASM module execution: When the command references a .wasm file, it is loaded and run via Wasmtime + WASI preview1 with full isolation: preopened directories, fuel metering, epoch interruption, and captured I/O.

Unknown commands return exit code 127: “command not found in WASM sandbox”.

Filesystem Isolation

~/.moltis/sandbox/wasm/<session-key>/
  home/        preopened as /home/sandbox (rw)
  tmp/         preopened as /tmp (rw)

Home persistence is respected:

• shared: uses data_dir()/sandbox/home/shared/wasm/
• session: uses data_dir()/sandbox/wasm/<session-id>/
• off: per-session, cleaned up on cleanup()

Resource Limits

• Fuel metering: store.set_fuel(fuel_limit) — limits WASM instruction count (Tier 2 only)
• Epoch interruption: background thread ticks epochs, store traps on deadline (Tier 2 only)
• Memory: wasm_config.memory_reservation(bytes) — Wasmtime memory limits (Tier 2 only)

Configuration

[tools.exec.sandbox]
backend = "wasm"

# WASM-specific settings
wasm_fuel_limit = 1000000000       # instruction fuel (default: 1 billion)
wasm_epoch_interval_ms = 100       # epoch interruption interval (default: 100ms)

[tools.exec.sandbox.resource_limits]
memory_limit = "512M"    # Wasmtime memory reservation

Limitations

• Built-in commands cover common coreutils but not a full shell
• No pipe support yet (planned via busybox.wasm in future)
• No network access from WASM modules
• .wasm modules must target WASI preview1

When to Use

The WASM sandbox is a good fit when:

• You want filesystem-isolated execution without container overhead
• You need a sandboxed environment on platforms without Docker or Apple Container
• You are running .wasm modules and want fuel-metered, time-bounded execution

Compile-Time Feature

The WASM sandbox is gated behind the wasm cargo feature, which is enabled by default. To build without Wasmtime (saves ~30 MB binary size):

cargo build --release --no-default-features --features lightweight

When the feature is disabled and the config requests backend = "wasm", Moltis falls back to restricted-host with a warning.

Restricted Host Sandbox

The restricted-host sandbox provides lightweight isolation by running commands on the host via sh -c with environment clearing and ulimit resource wrappers. This is the fallback when no container runtime is available.

How It Works

When the restricted-host sandbox runs a command, it:

1. Clears the environment — all inherited environment variables are removed
2. Sets a restricted PATH — only /usr/local/bin:/usr/bin:/bin
3. Sets HOME to /tmp — prevents access to the user’s home directory
4. Applies resource limits via shell ulimit:
   • ulimit -u (max processes) from pids_max config (default: 256)
   • ulimit -n 1024 (max open files)
   • ulimit -t (CPU seconds) from cpu_quota config (default: 300s)
   • ulimit -v (virtual memory) from memory_limit config (default: 512M)
5. Enforces a timeout via tokio::time::timeout

User-specified environment variables from opts.env are re-applied after the environment is cleared, so the LLM tool can still pass required variables.

Limitations

• No filesystem isolation — commands run on the host filesystem
• No network isolation — commands can make network requests
• ulimit enforcement is best-effort
• No image building — moltis sandbox build returns immediately

For production use with untrusted workloads, prefer Apple Container or Docker.

No sandbox

If no runtime is found (and the wasm feature is disabled), commands execute directly on the host. The startup banner will show a warning. This is not recommended for untrusted workloads.

Failover Chain

Moltis wraps the primary sandbox backend with automatic failover:

• Apple Container → Docker → Restricted Host: if Apple Container enters a corrupted state (stale metadata, missing config, VM boot failure), Moltis fails over to Docker. If Docker is unavailable, it uses restricted-host.
• Docker → Restricted Host: if Docker loses its daemon connection during a session, Moltis fails over to the restricted-host sandbox.

Failover is sticky for the lifetime of the gateway process — once triggered, all subsequent commands use the fallback backend. Restart the gateway to retry the primary backend.

Failover triggers:

Per-session overrides

The web UI allows toggling sandboxing per session and selecting a custom container image. These overrides persist across gateway restarts.

Home persistence

By default, /home/sandbox is persisted in a shared host folder so that CLI auth/config files survive container recreation. You can change this with home_persistence:

[tools.exec.sandbox]
home_persistence = "session"   # "off", "session", or "shared" (default)
# shared_home_dir = "/path/to/shared-home"  # optional, used when mode is "shared"

• off: no home mount, container home is ephemeral
• session: mount a per-session host folder to /home/sandbox
• shared: mount one shared host folder to /home/sandbox for all sessions (defaults to data_dir()/sandbox/home/shared, or shared_home_dir if set)

Moltis stores persisted homes under data_dir()/sandbox/home/.

Docker-in-Docker workspace mounts

When Moltis runs inside a container and launches Docker-backed sandboxes via a mounted container socket, the sandbox bind mount source must be a host-visible path. Moltis auto-detects this by inspecting the parent container’s mounts. If that lookup fails or you want to pin the value explicitly, set host_data_dir:

[tools.exec.sandbox]
host_data_dir = "/srv/moltis/data"

This remaps sandbox workspace mounts and default sandbox persistence paths from the guest data_dir() to the host path you provide. It is mainly an override for Docker-in-Docker deployments where mount auto-detection is unavailable or ambiguous.

Network policy

By default, sandbox containers have no network access (no_network = true). For tasks that need filtered internet access, use trusted network mode — a proxy-based allowlist that lets containers reach approved domains while blocking everything else.

[tools.exec.sandbox]
network = "trusted"
trusted_domains = ["registry.npmjs.org", "github.com"]

See Trusted Network for full configuration and the network audit log.

Note: Home persistence applies to Docker, Apple Container, and WASM backends. The restricted-host backend uses HOME=/tmp and does not mount persistent storage.

Resource limits

[tools.exec.sandbox.resource_limits]
memory_limit = "512M"
cpu_quota = 1.0
pids_max = 256

How resource limits are applied depends on the backend:

Comparison

Trusted Network Mode

Trusted network mode gives sandbox containers filtered internet access through a local HTTP proxy, so LLM-generated code can reach approved domains (package registries, APIs) while everything else is blocked.

Why

By default, sandbox containers run with no_network = true — full network isolation. This is the safest option but breaks any task that needs to install packages, fetch data, or call an API.

Setting no_network = false opens the network entirely, which defeats much of the sandbox’s purpose: a malicious command could exfiltrate data or download additional payloads.

Trusted network mode sits between these extremes. It routes all outbound traffic through a filtering proxy that only allows connections to domains you explicitly trust.

┌──────────────┐      CONNECT        ┌────────────┐       ┌──────────────┐
│   Sandbox    │ ──────────────────▶  │   Proxy    │ ────▶ │  github.com  │ ✓
│  Container   │                      │ :18791     │       └──────────────┘
│              │      CONNECT         │            │       ┌──────────────┐
│  HTTP_PROXY  │ ──────────────────▶  │  Domain    │ ──✗─▶ │  evil.com    │ ✗
│  = proxy:18791                      │  Filter    │       └──────────────┘
└──────────────┘                      └────────────┘

Configuration

Enable trusted network mode in moltis.toml:

[tools.exec.sandbox]
network = "trusted"
trusted_domains = [
  # Package registries
  "registry.npmjs.org",
  "pypi.org",
  "files.pythonhosted.org",
  "crates.io",
  "static.crates.io",

  # Git hosting
  "github.com",
  "gitlab.com",

  # Common APIs
  "api.openai.com",
  "httpbin.org",
]

Network policies

Domain patterns

The trusted_domains list supports three pattern types:

How the proxy works

When network = "trusted", the gateway starts an HTTP CONNECT proxy on 127.0.0.1:18791 at startup. Sandbox containers are configured to route traffic through this proxy via HTTP_PROXY / HTTPS_PROXY environment variables.

For each connection the proxy:

1. Extracts the target domain from the CONNECT request (or Host header for plain HTTP).
2. Checks the domain against the allowlist in DomainApprovalManager.
3. If allowed — opens a TCP tunnel to the target and relays data bidirectionally.
4. If denied — returns 403 Forbidden and logs the attempt.

Both allowed and denied requests are recorded in the network audit log.

Network Audit

Every proxied request is logged to an in-memory ring buffer (2048 entries) and persisted to ~/.moltis/network-audit.jsonl. The audit log is accessible from:

• Settings > Network Audit in the web UI
• RPC methods: network.audit.list, network.audit.tail, network.audit.stats
• WebSocket events: network.audit.entry streams entries in real time

Audit entry fields

Filtering the audit log

The web UI provides real-time filtering by:

• Domain — free-text search across domain names
• Protocol — filter by https, http, or connect
• Action — show only allowed or denied entries

The RPC methods accept the same filter parameters:

{
  "method": "network.audit.list",
  "params": {
    "domain": "github",
    "protocol": "https",
    "action": "denied",
    "limit": 100
  }
}

Audit stats

network.audit.stats returns aggregate counts:

{
  "total": 847,
  "allowed": 812,
  "denied": 35,
  "by_domain": [
    { "domain": "registry.npmjs.org", "count": 423 },
    { "domain": "github.com", "count": 312 }
  ]
}

Recommended domain lists

Node.js / npm

trusted_domains = [
  "registry.npmjs.org",
  "*.npmjs.org",
]

Python / pip

trusted_domains = [
  "pypi.org",
  "files.pythonhosted.org",
]

Rust / cargo

trusted_domains = [
  "crates.io",
  "static.crates.io",
  "index.crates.io",
]

Git operations

trusted_domains = [
  "github.com",
  "gitlab.com",
  "bitbucket.org",
]

Relationship to other settings

• no_network = true (legacy) is equivalent to network = "blocked". When network is set, it takes precedence over no_network.
• mode = "off" disables sandboxing entirely — network policy has no effect because commands run directly on the host.
• Resource limits (memory_limit, cpu_quota, pids_max) apply independently of the network policy.

Troubleshooting

Proxy not starting: Check the gateway startup log for trusted-network proxy started on port 18791. If missing, verify network = "trusted" is set in moltis.toml.

Connections timing out: Some tools don’t respect HTTP_PROXY. Verify the tool uses the proxy by checking the audit log — if no entries appear for the domain, the tool is bypassing the proxy.

Too many denied entries: Review the audit log to identify legitimate domains being blocked, then add them to trusted_domains.

Voice Services

Moltis provides text-to-speech (TTS) and speech-to-text (STT) capabilities through the moltis-voice crate and gateway integration.

Feature Flag

Voice services are behind the voice cargo feature, enabled by default:

# Cargo.toml (gateway crate)
[features]
default = ["voice", ...]
voice = ["dep:moltis-voice"]

To disable voice features at compile time:

cargo build --no-default-features --features "file-watcher,tailscale,tls,web-ui"

When disabled:

• TTS/STT RPC methods are not registered
• Voice settings section is hidden in the UI
• Microphone button is hidden in the chat interface
• voice_enabled: false is set in the gon data

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Voice Crate                            │
│                   (crates/voice/)                           │
├─────────────────────────────────────────────────────────────┤
│  TtsProvider trait         │  SttProvider trait             │
│  ├─ ElevenLabsTts          │  ├─ WhisperStt (OpenAI)        │
│  ├─ OpenAiTts              │  ├─ GroqStt (Groq)             │
│  ├─ GoogleTts              │  ├─ DeepgramStt                │
│  ├─ PiperTts (local)       │  ├─ GoogleStt                  │
│  └─ CoquiTts (local)       │  ├─ MistralStt                 │
│                            │  ├─ VoxtralLocalStt (local)    │
│                            │  ├─ WhisperCliStt (local)      │
│                            │  └─ SherpaOnnxStt (local)      │
└─────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│                    Gateway Services                         │
│                (crates/gateway/src/voice.rs)                │
├─────────────────────────────────────────────────────────────┤
│  LiveTtsService            │  LiveSttService                │
│  (wraps TTS providers)     │  (wraps STT providers)         │
└─────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│                     RPC Methods                             │
├─────────────────────────────────────────────────────────────┤
│  tts.status, tts.providers, tts.enable, tts.disable,        │
│  tts.convert, tts.setProvider                               │
│  stt.status, stt.providers, stt.transcribe, stt.setProvider │
└─────────────────────────────────────────────────────────────┘

Text-to-Speech (TTS)

Supported Providers

Moltis supports multiple TTS providers across cloud and local backends.

More voice providers are coming soon.

Configuration

Set API keys via environment variables:

export ELEVENLABS_API_KEY=your-key-here
export OPENAI_API_KEY=your-key-here

Or configure in moltis.toml:

[voice.tts]
enabled = true
# provider = "openai"    # Omit to auto-select the first configured provider
providers = []           # Optional UI allowlist, empty = show all TTS providers
auto = "off"             # "always", "off", "inbound", "tagged"
max_text_length = 2000

[voice.tts.elevenlabs]
api_key = "sk-..."
voice_id = "21m00Tcm4TlvDq8ikWAM"  # Rachel (default)
model = "eleven_flash_v2_5"
stability = 0.5
similarity_boost = 0.75

[voice.tts.openai]
# No api_key needed if OpenAI is configured as an LLM provider or OPENAI_API_KEY is set.
# api_key = "sk-..."
voice = "alloy"  # alloy, echo, fable, onyx, nova, shimmer
model = "tts-1"
speed = 1.0

[voice.tts.google]
api_key = "..."  # Google Cloud API key
voice = "en-US-Neural2-D"  # See Google Cloud TTS voices
language_code = "en-US"
speaking_rate = 1.0

# Local providers - no API key required

[voice.tts.piper]
# binary_path = "/usr/local/bin/piper"  # optional, searches PATH
model_path = "~/.moltis/models/en_US-lessac-medium.onnx"  # required
# config_path = "~/.moltis/models/en_US-lessac-medium.onnx.json"  # optional
# speaker_id = 0  # for multi-speaker models
# length_scale = 1.0  # speaking rate (lower = faster)

[voice.tts.coqui]
endpoint = "http://localhost:5002"  # Coqui TTS server
# model = "tts_models/en/ljspeech/tacotron2-DDC"  # optional

Local TTS Provider Setup

Piper TTS

Piper is a fast, local neural text-to-speech system that runs entirely offline.

1. Install Piper:

   # Via pip
   pip install piper-tts
   
   # Or download pre-built binaries from:
   # https://github.com/rhasspy/piper/releases
   

2. Download a voice model from Piper Voices:

   mkdir -p ~/.moltis/models
   curl -L -o ~/.moltis/models/en_US-lessac-medium.onnx \
     https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx
   

3. Configure in moltis.toml:

   [voice.tts]
   provider = "piper"
   
   [voice.tts.piper]
   model_path = "~/.moltis/models/en_US-lessac-medium.onnx"
   

Coqui TTS

Coqui TTS is a high-quality neural TTS with voice cloning capabilities.

1. Install and start the server:

   # Via pip
   pip install TTS
   tts-server --model_name tts_models/en/ljspeech/tacotron2-DDC
   
   # Or via Docker
   docker run -p 5002:5002 ghcr.io/coqui-ai/tts
   

2. Configure in moltis.toml:

   [voice.tts]
   provider = "coqui"
   
   [voice.tts.coqui]
   endpoint = "http://localhost:5002"
   

Browse available models at Coqui TTS Models.

RPC Methods

tts.status

Get current TTS status.

Response:

{
  "enabled": true,
  "provider": "elevenlabs",
  "auto": "off",
  "maxTextLength": 2000,
  "configured": true
}

tts.providers

List available TTS providers.

Response:

[
  { "id": "elevenlabs", "name": "ElevenLabs", "configured": true },
  { "id": "openai", "name": "OpenAI", "configured": false }
]

tts.enable

Enable TTS with optional provider selection.

Request:

{ "provider": "elevenlabs" }

Response:

{ "enabled": true, "provider": "elevenlabs" }

tts.disable

Disable TTS.

Response:

{ "enabled": false }

tts.convert

Convert text to speech.

Request:

{
  "text": "Hello, how can I help you today?",
  "provider": "elevenlabs",
  "voiceId": "21m00Tcm4TlvDq8ikWAM",
  "model": "eleven_flash_v2_5",
  "format": "mp3",
  "speed": 1.0,
  "stability": 0.5,
  "similarityBoost": 0.75
}

Response:

{
  "audio": "base64-encoded-audio-data",
  "format": "mp3",
  "mimeType": "audio/mpeg",
  "durationMs": 2500,
  "size": 45000
}

Audio Formats:

• mp3 (default) - Widely compatible
• opus / ogg - Good for Telegram voice notes
• aac - Apple devices
• pcm - Raw audio

tts.setProvider

Change the active TTS provider.

Request:

{ "provider": "openai" }

Auto-Speak Modes

Speech-to-Text (STT)

Supported Providers

Moltis supports multiple STT providers across cloud and local backends.

More voice providers are coming soon.

Configuration

[voice.stt]
enabled = true
# provider = "whisper"  # Omit to auto-select the first configured provider
providers = []          # Optional UI allowlist, empty = show all STT providers

# Cloud providers - API key required
[voice.stt.whisper]
# No api_key needed if OpenAI is configured as an LLM provider or OPENAI_API_KEY is set.
# api_key = "sk-..."
model = "whisper-1"
language = "en"     # Optional ISO 639-1 hint

[voice.stt.groq]
api_key = "gsk_..."
model = "whisper-large-v3-turbo"  # default
language = "en"

[voice.stt.deepgram]
api_key = "..."
model = "nova-3"  # default
language = "en"
smart_format = true

[voice.stt.google]
api_key = "..."
language = "en-US"
# model = "latest_long"  # optional

[voice.stt.mistral]
api_key = "..."
model = "voxtral-mini-latest"  # default
language = "en"

# Local providers - no API key, requires server or binary

# Voxtral local via vLLM server
[voice.stt.voxtral_local]
# endpoint = "http://localhost:8000"  # default vLLM endpoint
# model = "mistralai/Voxtral-Mini-3B-2507"  # optional, server default
# language = "en"  # optional

[voice.stt.whisper_cli]
# binary_path = "/usr/local/bin/whisper-cli"  # optional, searches PATH
model_path = "~/.moltis/models/ggml-base.en.bin"  # required
language = "en"

[voice.stt.sherpa_onnx]
# binary_path = "/usr/local/bin/sherpa-onnx-offline"  # optional
model_dir = "~/.moltis/models/sherpa-onnx-whisper-tiny.en"  # required
language = "en"

Local Provider Setup

Voxtral via vLLM

Voxtral is an open-weights model from Mistral AI that can run locally using vLLM. It supports 13 languages with fast transcription.

Requirements:

• Python 3.10+
• CUDA-capable GPU with ~9.5GB VRAM (or CPU with more memory)
• vLLM with audio support

Setup:

1. Install vLLM with audio support:

   pip install "vllm[audio]"
   

2. Start the vLLM server:

   vllm serve mistralai/Voxtral-Mini-3B-2507 \
     --tokenizer_mode mistral \
     --config_format mistral \
     --load_format mistral
   

   The server exposes an OpenAI-compatible endpoint at http://localhost:8000.

3. Configure in moltis.toml:

   [voice.stt]
   provider = "voxtral-local"
   
   [voice.stt.voxtral_local]
   # Default endpoint works if vLLM is running locally
   # endpoint = "http://localhost:8000"
   

Supported Languages: English, French, German, Spanish, Portuguese, Italian, Dutch, Polish, Swedish, Norwegian, Danish, Finnish, Arabic

Note: Unlike the embedded local providers (whisper.cpp, sherpa-onnx), this requires running vLLM as a separate server process. The model is downloaded automatically on first vLLM startup.

whisper.cpp

1. Install the binary:

   # macOS
   brew install whisper-cpp
   
   # From source: https://github.com/ggerganov/whisper.cpp
   

2. Download a model from Hugging Face:

   mkdir -p ~/.moltis/models
   curl -L -o ~/.moltis/models/ggml-base.en.bin \
     https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin
   

3. Configure in moltis.toml:

   [voice.stt]
   provider = "whisper-cli"
   
   [voice.stt.whisper_cli]
   model_path = "~/.moltis/models/ggml-base.en.bin"
   

sherpa-onnx

1. Install following the official docs

2. Download a model from the model list

3. Configure in moltis.toml:

   [voice.stt]
   provider = "sherpa-onnx"
   
   [voice.stt.sherpa_onnx]
   model_dir = "~/.moltis/models/sherpa-onnx-whisper-tiny.en"
   

RPC Methods

stt.status

Get current STT status.

Response:

{
  "enabled": true,
  "provider": "whisper",
  "configured": true
}

stt.providers

List available STT providers.

Response:

[
  { "id": "whisper", "name": "OpenAI Whisper", "configured": true },
  { "id": "groq", "name": "Groq", "configured": false },
  { "id": "deepgram", "name": "Deepgram", "configured": false },
  { "id": "google", "name": "Google Cloud", "configured": false },
  { "id": "mistral", "name": "Mistral AI", "configured": false },
  { "id": "voxtral-local", "name": "Voxtral (Local)", "configured": false },
  { "id": "whisper-cli", "name": "whisper.cpp", "configured": false },
  { "id": "sherpa-onnx", "name": "sherpa-onnx", "configured": false }
]

stt.transcribe

Transcribe audio to text.

Request:

{
  "audio": "base64-encoded-audio-data",
  "format": "mp3",
  "language": "en",
  "prompt": "Technical discussion about Rust programming"
}

Response:

{
  "text": "Hello, how are you today?",
  "language": "en",
  "confidence": null,
  "durationSeconds": 2.5,
  "words": [
    { "word": "Hello", "start": 0.0, "end": 0.5 },
    { "word": "how", "start": 0.6, "end": 0.8 },
    { "word": "are", "start": 0.9, "end": 1.0 },
    { "word": "you", "start": 1.1, "end": 1.3 },
    { "word": "today", "start": 1.4, "end": 1.8 }
  ]
}

Parameters:

• audio (required): Base64-encoded audio data
• format: Audio format (mp3, opus, ogg, aac, pcm)
• language: ISO 639-1 code to improve accuracy
• prompt: Context hint (terminology, topic)

stt.setProvider

Change the active STT provider.

Request:

{ "provider": "groq" }

Valid provider IDs: whisper, groq, deepgram, google, mistral, voxtral-local, whisper-cli, sherpa-onnx

Code Structure

Voice Crate (crates/voice/)

src/
├── lib.rs           # Crate entry, re-exports
├── config.rs        # VoiceConfig, TtsConfig, SttConfig
├── tts/
│   ├── mod.rs       # TtsProvider trait, AudioFormat, types
│   ├── elevenlabs.rs # ElevenLabs implementation
│   ├── openai.rs    # OpenAI TTS implementation
│   ├── google.rs    # Google Cloud TTS implementation
│   ├── piper.rs     # Piper local TTS implementation
│   └── coqui.rs     # Coqui TTS server implementation
└── stt/
    ├── mod.rs          # SttProvider trait, Transcript types
    ├── whisper.rs      # OpenAI Whisper implementation
    ├── groq.rs         # Groq Whisper implementation
    ├── deepgram.rs     # Deepgram implementation
    ├── google.rs       # Google Cloud Speech-to-Text
    ├── mistral.rs      # Mistral AI Voxtral cloud implementation
    ├── voxtral_local.rs # Voxtral via local vLLM server
    ├── cli_utils.rs    # Shared utilities for CLI providers
    ├── whisper_cli.rs  # whisper.cpp CLI wrapper
    └── sherpa_onnx.rs  # sherpa-onnx CLI wrapper

Key Traits

#![allow(unused)]
fn main() {
/// Text-to-Speech provider trait
#[async_trait]
pub trait TtsProvider: Send + Sync {
    fn id(&self) -> &'static str;
    fn name(&self) -> &'static str;
    fn is_configured(&self) -> bool;
    async fn voices(&self) -> Result<Vec<Voice>>;
    async fn synthesize(&self, request: SynthesizeRequest) -> Result<AudioOutput>;
}

/// Speech-to-Text provider trait
#[async_trait]
pub trait SttProvider: Send + Sync {
    fn id(&self) -> &'static str;
    fn name(&self) -> &'static str;
    fn is_configured(&self) -> bool;
    async fn transcribe(&self, request: TranscribeRequest) -> Result<Transcript>;
}
}

Gateway Integration (crates/gateway/src/voice.rs)

• LiveTtsService: Wraps TTS providers, implements TtsService trait
• LiveSttService: Wraps STT providers, implements SttService trait
• NoopSttService: No-op for when STT is not configured

Security

• API keys are stored using secrecy::Secret<String> to prevent accidental logging
• Debug output redacts all secret values
• Keys can be set via environment variables or config file

Adding New Providers

TTS Provider

1. Create crates/voice/src/tts/newprovider.rs
2. Implement TtsProvider trait
3. Re-export from crates/voice/src/tts/mod.rs
4. Add to LiveTtsService in gateway

STT Provider

1. Create crates/voice/src/stt/newprovider.rs
2. Implement SttProvider trait
3. Re-export from crates/voice/src/stt/mod.rs
4. Add to LiveSttService in gateway

Web UI Integration

The voice feature integrates with the web UI:

• Microphone button: Record voice input in the chat interface
• Settings page: Configure and enable/disable voice providers
• Auto-detection: API keys are detected from environment variables and LLM provider configs
• Toggle switches: Enable/disable providers without removing configuration
• Setup instructions: Step-by-step guides for local provider installation

Future Enhancements

• Streaming TTS: Chunked audio delivery for lower latency
• VoiceWake: Wake word detection and continuous listening
• Audio playback: Play TTS responses directly in the chat
• Channel Integration: Auto-transcribe Telegram voice messages
• Per-Agent Voices: Different voices for different agents

Channels

Moltis connects to messaging platforms through channels. Each channel type has a distinct inbound mode, determining how it receives messages, and a set of capabilities that control what features are available.

Supported Channels

Inbound Modes

Polling

The bot periodically fetches new messages from the platform API. No public URL or open port is needed. Used by Telegram.

Gateway / WebSocket

The bot opens a persistent outbound WebSocket connection to the platform and receives events in real time. No public URL needed. Used by Discord and WhatsApp.

Socket Mode

Similar to a gateway connection, but uses the platform’s Socket Mode protocol. No public URL needed. Used by Slack.

Webhook

The platform sends HTTP POST requests to a publicly reachable endpoint on your server. You must configure the messaging endpoint URL in the platform’s settings. Used by Microsoft Teams.

None (Send-Only)

For channels that only send outbound messages and do not receive inbound traffic. No channels currently use this mode, but it is available for future integrations (e.g. email, SMS).

Capabilities Reference

Setup

Each channel is configured in moltis.toml under [channels]:

[channels.telegram.my_bot]
token = "123456:ABC-DEF..."
dm_policy = "allowlist"
allowlist = ["alice", "bob"]

[channels.msteams.my_teams_bot]
app_id = "..."
app_password = "..."

[channels.discord.my_discord_bot]
token = "..."

[channels.slack.my_slack_bot]
bot_token = "xoxb-..."
app_token = "xapp-..."

[channels.whatsapp.my_wa]
dm_policy = "open"

For detailed configuration, see the per-channel pages: Telegram, Discord, Slack, WhatsApp.

You can also use the web UI’s Channels tab for guided setup with each platform.

Proactive Outbound Messaging

Agents are not limited to replying in the current chat. Moltis supports three main outbound patterns:

• send_message tool for direct proactive messages to any configured channel account/chat
• Cron job delivery for background jobs that should post their final output to a channel
• Heartbeat delivery for periodic heartbeat acknowledgements sent to a chosen chat

Example send_message tool call:

{
  "account_id": "my-telegram-bot",
  "to": "123456789",
  "text": "Deployment finished successfully."
}

account_id is the configured channel account name from moltis.toml, and to is the destination chat, peer, or room identifier for that platform.

Access Control

All channels share the same access control model with three settings:

DM Policy

Controls who can send direct messages to the bot.

Group Policy

Controls who can interact with the bot in group chats / channels / guilds.

The group allowlist field name varies by channel: group_allowlist (Telegram, WhatsApp, MS Teams), guild_allowlist (Discord), channel_allowlist (Slack).

Mention Mode

Controls when the bot responds in groups (does not apply to DMs).

Allowlist Matching

All allowlist fields across all channels share the same matching behavior:

• Values are strings — even for numeric IDs, use "123456789" not 123456789
• Case-insensitive — "Alice" matches "alice"
• Glob wildcards — "admin_*", "*@example.com", "user_*_vip"
• Multiple identifiers — both the user’s numeric ID and username are checked (where applicable)

OTP Self-Approval

Channels that support OTP (Telegram, Discord, WhatsApp) allow non-allowlisted users to self-approve by entering a 6-digit code. The code appears in the web UI under Channels > Senders. See each channel’s page for details.

Telegram

Moltis can connect to Telegram as a bot, letting you chat with your agent from any Telegram conversation. The integration uses Telegram’s Bot API with long polling — no public URL or webhook endpoint is required.

How It Works

┌──────────────────────────────────────────────────────┐
│                 Telegram Bot API                      │
│            (api.telegram.org/bot...)                  │
└──────────────────┬───────────────────────────────────┘
                   │  long polling (getUpdates)
                   ▼
┌──────────────────────────────────────────────────────┐
│              moltis-telegram crate                    │
│  ┌────────────┐  ┌────────────┐  ┌────────────────┐  │
│  │  Handler   │  │  Outbound  │  │     Plugin     │  │
│  │ (inbound)  │  │ (replies)  │  │  (lifecycle)   │  │
│  └────────────┘  └────────────┘  └────────────────┘  │
└──────────────────┬───────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────┐
│                 Moltis Gateway                        │
│         (chat dispatch, tools, memory)                │
└──────────────────────────────────────────────────────┘

The bot connects outward to Telegram’s servers via polling. No port forwarding, public domain, or TLS certificate is needed. This makes it easy to run on a home machine or behind a NAT.

Prerequisites

Before configuring Moltis, create a Telegram bot:

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts to choose a name and username
3. Copy the bot token (e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

Configuration

Add a [channels.telegram.<account-id>] section to your moltis.toml:

[channels.telegram.my-bot]
token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

Make sure "telegram" is included in channels.offered so the Web UI shows the Telegram option:

[channels]
offered = ["telegram"]

Configuration Fields

Full Example

[channels]
offered = ["telegram"]

[channels.telegram.my-bot]
token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
dm_policy = "allowlist"
group_policy = "open"
mention_mode = "mention"
allowlist = ["123456789", "alice_username"]
group_allowlist = ["-1001234567890"]
reply_to_message = true
model = "claude-sonnet-4-20250514"
model_provider = "anthropic"
otp_self_approval = true
stream_mode = "edit_in_place"
edit_throttle_ms = 300

Per-User and Per-Channel Model Overrides

You can override the model for specific users or group chats:

[channels.telegram.my-bot]
token = "..."
model = "claude-sonnet-4-20250514"
model_provider = "anthropic"

[channels.telegram.my-bot.channel_overrides."-1001234567890"]
model = "gpt-4o"
model_provider = "openai"

[channels.telegram.my-bot.user_overrides."123456789"]
model = "claude-opus-4-20250514"
model_provider = "anthropic"

User overrides take priority over channel overrides, which take priority over the account default.

Access Control

Telegram uses the same gating system as Discord and other channels.

DM Policy

Controls who can send direct messages to the bot.

Group Policy

Controls who can interact with the bot in group chats.

Mention Mode

Controls when the bot responds in groups (does not apply to DMs).

Allowlist Matching

Allowlist entries support:

• Exact match (case-insensitive): "alice", "123456789"
• Glob wildcards: "admin_*", "*_bot", "user_*_vip"

Both the user’s numeric Telegram ID and their username are checked against the allowlist. For example, if a user has ID 123456789 and username alice, either "123456789" or "alice" in the allowlist grants access.

OTP Self-Approval

When dm_policy = "allowlist" and otp_self_approval = true (the default), unknown users who DM the bot receive a verification challenge:

1. User sends a DM to the bot
2. Bot responds with a challenge prompt (the 6-digit code is not shown to the user)
3. The code appears in the Moltis web UI under Channels > Senders
4. The bot owner shares the code with the user out-of-band
5. User replies with the 6-digit code
6. On success, the user is automatically added to the allowlist

After 3 failed attempts, the user is locked out for otp_cooldown_secs seconds (default: 300). Codes expire after 5 minutes.

Set otp_self_approval = false if you want to manually approve every user from the web UI.

Streaming

By default (stream_mode = "edit_in_place"), the bot sends an initial message after stream_min_initial_chars characters (default: 30) and then edits it in place as tokens arrive, throttled to at most one edit every edit_throttle_ms milliseconds (default: 300).

Set stream_mode = "off" to disable streaming and send the full response as a single message.

When stream_notify_on_complete = true, the bot sends a short non-silent message after streaming finishes. This can trigger a Telegram push notification on the user’s device (since silent edits don’t always trigger notifications).

Finding Your Telegram User ID

To find your numeric Telegram user ID (for the allowlist):

1. Message @userinfobot on Telegram
2. It replies with your user ID, first name, and username
3. Use the numeric ID as a string in your config: allowlist = ["123456789"]

Alternatively, use your Telegram username (without the @): allowlist = ["your_username"].

Web UI Setup

You can also configure Telegram through the web interface:

1. Open Settings > Channels
2. Click Connect Telegram
3. Enter an account ID (any alias) and your bot token
4. Adjust DM policy, mention mode, and allowlist as needed
5. Click Connect

The same form is available during onboarding when Telegram is in channels.offered.

Troubleshooting

Bot doesn’t respond

• Verify the bot token is correct (ask @BotFather for /token if unsure)
• Check dm_policy — if set to "allowlist", make sure your user ID or username is listed in allowlist
• An empty allowlist with dm_policy = "allowlist" blocks all DMs
• Check group_policy — if "disabled", group messages are ignored
• Look at logs: RUST_LOG=moltis_telegram=debug moltis

“allowed_users” doesn’t work

The field name is allowlist, not allowed_users. If you’re migrating from OpenClaw, note that the field was renamed. Values must also be strings (e.g. ["123456789"]), not integers.

Bot responds to everyone

• Check that dm_policy = "allowlist" is set (it’s the default)
• Verify you have entries in allowlist — an empty allowlist with dm_policy = "allowlist" blocks everyone, but dm_policy = "open" allows everyone

Bot doesn’t respond in groups

• Check mention_mode — if set to "mention", you must @mention the bot
• Check group_policy — if "disabled", group messages are ignored
• Check group_allowlist — if non-empty, the group must be listed

Discord

Moltis can connect to Discord as a bot, letting you chat with your agent from any Discord server or DM. The integration uses Discord’s Gateway API via a persistent WebSocket connection — no public URL or webhook endpoint is required.

How It Works

┌──────────────────────────────────────────────────────┐
│                   Discord Gateway                     │
│              (wss://gateway.discord.gg)               │
└──────────────────┬───────────────────────────────────┘
                   │  persistent WebSocket
                   ▼
┌──────────────────────────────────────────────────────┐
│               moltis-discord crate                    │
│  ┌────────────┐  ┌────────────┐  ┌────────────────┐  │
│  │  Handler   │  │  Outbound  │  │     Plugin     │  │
│  │ (inbound)  │  │ (replies)  │  │  (lifecycle)   │  │
│  └────────────┘  └────────────┘  └────────────────┘  │
└──────────────────┬───────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────┐
│                 Moltis Gateway                        │
│         (chat dispatch, tools, memory)                │
└──────────────────────────────────────────────────────┘

The bot connects outward to Discord’s servers. Unlike Microsoft Teams (which requires an inbound webhook), Discord needs no port forwarding, no public domain, and no TLS certificate. This makes it especially easy to run on a home machine or behind a NAT.

Prerequisites

Before configuring Moltis, create a Discord bot:

1. Go to the Discord Developer Portal
2. Click New Application and give it a name
3. Navigate to Bot in the left sidebar
4. Click Reset Token and copy the bot token
5. Under Privileged Gateway Intents, enable Message Content Intent
6. Navigate to OAuth2 → URL Generator
   • Scopes: bot
   • Bot Permissions: Send Messages, Attach Files, Read Message History, Add Reactions
7. Copy the generated URL and open it to invite the bot to your server

Configuration

Add a [channels.discord.<account-id>] section to your moltis.toml:

[channels.discord.my-bot]
token = "MTIzNDU2Nzg5.example.bot-token"

Make sure "discord" is included in channels.offered so the Web UI shows the Discord option:

[channels]
offered = ["telegram", "discord"]

Configuration Fields

Full Example

[channels]
offered = ["telegram", "discord"]

[channels.discord.my-bot]
token = "MTIzNDU2Nzg5.example.bot-token"
dm_policy = "allowlist"
group_policy = "open"
mention_mode = "mention"
allowlist = ["alice", "bob"]
guild_allowlist = ["123456789012345678"]
reply_to_message = true
ack_reaction = "👀"
model = "gpt-4o"
model_provider = "openai"
activity = "with AI"
activity_type = "custom"
status = "online"
otp_self_approval = true

Access Control

Discord uses the same gating system as Telegram and Microsoft Teams:

DM Policy

Controls who can send direct messages to the bot.

Group Policy

Controls who can interact with the bot in guild (server) channels.

Mention Mode

Controls when the bot responds in guild channels (does not apply to DMs).

Guild Allowlist

If guild_allowlist is non-empty, messages from guilds not in the list are silently dropped — regardless of group_policy. This provides a server-level filter on top of the channel-level policy.

OTP Self-Approval

When dm_policy = "allowlist" and otp_self_approval = true (the default), unknown users who DM the bot receive a verification challenge. The flow:

1. User sends a DM to the bot
2. Bot responds with a challenge prompt (the 6-digit code is not shown to the user)
3. The code appears in the Moltis web UI under Channels → Senders
4. The bot owner shares the code with the user out-of-band
5. User replies with the 6-digit code
6. On success, the user is automatically added to the allowlist

After 3 failed attempts, the user is locked out for otp_cooldown_secs seconds (default: 300). Codes expire after 5 minutes.

Bot Presence

Configure the bot’s Discord presence (the “Playing…” / “Listening to…” status) using the activity, activity_type, and status fields:

[channels.discord.my-bot]
token = "..."
activity = "with AI"
activity_type = "custom"  # or "playing", "listening", "watching", "competing"
status = "online"         # or "idle", "dnd", "invisible"

The presence is set when the bot connects to the Discord gateway. If no activity or status is configured, the bot uses Discord’s default (online, no activity).

Slash Commands

The bot automatically registers native Discord slash commands when it connects:

Slash commands appear in Discord’s command palette (type / in any channel where the bot is present). Responses are ephemeral — only visible to the user who invoked the command.

Web UI Setup

You can also configure Discord through the web interface:

1. Open Settings → Channels
2. Click Connect Discord
3. Enter an account ID (any alias) and your bot token
4. Adjust DM policy, mention mode, and allowlist as needed
5. Click Connect

The same form is available during onboarding when Discord is in channels.offered.

Talking to Your Bot

Once the bot is connected there are several ways to interact with it.

In a Server

To use the bot in a Discord server you need to invite it first:

1. Go to the Discord Developer Portal
2. Select your application → OAuth2 → URL Generator
3. Scopes: check bot
4. Bot Permissions: check Send Messages, Read Message History, and Add Reactions
5. Copy the generated URL and open it in your browser
6. Select the server you want to add the bot to and confirm

Once the bot is in your server, @mention it in any channel to get a response (assuming mention_mode = "mention", the default). If you set mention_mode = "always" the bot responds to every message in allowed channels.

Via Direct Message

You can DM the bot directly from Discord — no shared server required:

1. Open Discord and go to Direct Messages
2. Click the New Message icon (or Find or start a conversation)
3. Search for the bot’s username and select it
4. Send a message

Without a Shared Server

DMs work even if you and the bot don’t share a server. Discord bots are reachable by username from any account. This makes DMs the simplest way to start chatting — just connect the bot in Moltis and message it directly.

Message Handling

Inbound Messages

When a message arrives from Discord:

1. Bot’s own messages are ignored
2. Guild allowlist is checked (if configured)
3. DM/group policy is evaluated
4. Mention mode is checked (guild messages only)
5. Bot mention prefix (@BotName) is stripped from the message text
6. The message is logged and dispatched to the chat engine
7. Commands (messages starting with /) are dispatched to the command handler

Outbound Messages

Discord enforces a 2,000-character limit per message. Moltis automatically splits long responses into multiple messages, preferring to break at newline boundaries and avoiding splits inside fenced code blocks.

Streaming uses edit-in-place — an initial message is sent after 30 characters and then updated every 500ms as tokens arrive. If the final text exceeds 2,000 characters, the first message is edited to the limit and overflow is sent as follow-up messages.

Reply-to-Message

Set reply_to_message = true to have the bot send responses as Discord replies (threaded to the user’s original message). The first chunk of a multi-chunk or streamed response carries the reply reference; follow-up chunks are sent as regular messages.

Ack Reactions

Set ack_reaction = "👀" (or any Unicode emoji) to have the bot react to the user’s message when processing starts. The reaction is removed once the response is complete. This provides a visual indicator that the bot has seen the message and is working on a reply.

Crate Structure

crates/discord/
├── Cargo.toml
└── src/
    ├── lib.rs         # Public exports
    ├── commands.rs    # Native Discord slash command registration
    ├── config.rs      # DiscordAccountConfig (token, policies, presence, OTP)
    ├── error.rs       # Error enum (Config, Gateway, Send, Channel)
    ├── handler.rs     # serenity EventHandler (inbound + OTP + interactions)
    ├── outbound.rs    # ChannelOutbound + ChannelStreamOutbound impls
    ├── plugin.rs      # ChannelPlugin + ChannelStatus impls
    └── state.rs       # AccountState + AccountStateMap (includes OtpState)

The crate implements the same trait set as moltis-telegram and moltis-msteams:

Troubleshooting

Bot doesn’t respond

• Verify Message Content Intent is enabled in the Developer Portal
• Check that the bot token is correct (reset it if unsure)
• Ensure the bot has been invited to the server with the right permissions
• Check dm_policy / group_policy — if set to "allowlist", make sure your username or guild ID is listed
• Look at logs: RUST_LOG=moltis_discord=debug moltis

“Gateway connection failed”

• Check your network connection — the bot connects outward to wss://gateway.discord.gg
• Firewalls or proxies that block outbound WebSocket connections will prevent the bot from connecting
• The token may have been revoked — regenerate it in the Developer Portal

Bot responds in DMs but not in guilds

• Check mention_mode — if set to "mention", you must @mention the bot
• Check group_policy — if "disabled", guild messages are ignored
• Check guild_allowlist — if non-empty, the guild must be listed

Slack

Moltis can connect to Slack as a bot, letting you chat with your agent from any Slack workspace. The integration supports both Socket Mode (default, no public URL needed) and Events API (webhook-based).

How It Works

┌──────────────────────────────────────────────────────┐
│                    Slack API                          │
│            (Socket Mode / Events API)                │
└──────────────────┬───────────────────────────────────┘
                   │  WebSocket (Socket Mode)
                   │  or HTTP POST (Events API)
                   ▼
┌──────────────────────────────────────────────────────┐
│                moltis-slack crate                     │
│  ┌────────────┐  ┌────────────┐  ┌────────────────┐  │
│  │  Handler   │  │  Outbound  │  │     Plugin     │  │
│  │ (inbound)  │  │ (replies)  │  │  (lifecycle)   │  │
│  └────────────┘  └────────────┘  └────────────────┘  │
└──────────────────┬───────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────┐
│                 Moltis Gateway                        │
│         (chat dispatch, tools, memory)                │
└──────────────────────────────────────────────────────┘

With Socket Mode (the default), the bot opens an outbound WebSocket connection to Slack — no public URL, port forwarding, or TLS certificate is needed. With Events API mode, Slack sends HTTP POST requests to your server, requiring a publicly reachable endpoint.

Prerequisites

Before configuring Moltis, create a Slack app:

1. Go to api.slack.com/apps and click Create New App
2. Choose From scratch, name the app, and select your workspace
3. Navigate to OAuth & Permissions and add these Bot Token Scopes:
   • app_mentions:read — read @mentions
   • chat:write — send messages
   • im:history — read DM history
   • im:read — view DM metadata
   • channels:history — read channel messages (for mention_mode = "always")
4. Click Install to Workspace and copy the Bot User OAuth Token (xoxb-...)
5. For Socket Mode (recommended):
   • Go to Socket Mode and enable it
   • Generate an App-Level Token (xapp-...) with the connections:write scope
6. For Events API mode:
   • Go to Event Subscriptions and enable it
   • Set the Request URL to your Moltis instance endpoint
   • Copy the Signing Secret from Basic Information
7. Under Event Subscriptions > Subscribe to bot events, add:
   • app_mention — when someone @mentions the bot
   • message.im — direct messages to the bot

Configuration

Add a [channels.slack.<account-id>] section to your moltis.toml:

[channels.slack.my-bot]
bot_token = "xoxb-your-bot-token"
app_token = "xapp-your-app-token"

Make sure "slack" is included in channels.offered:

[channels]
offered = ["slack"]

Configuration Fields

Full Example

[channels]
offered = ["slack"]

[channels.slack.my-bot]
bot_token = "xoxb-..."
app_token = "xapp-..."
connection_mode = "socket_mode"
dm_policy = "allowlist"
group_policy = "open"
mention_mode = "mention"
allowlist = ["U0123456789", "U9876543210"]
channel_allowlist = ["C0123456789"]
model = "claude-sonnet-4-20250514"
model_provider = "anthropic"
stream_mode = "edit_in_place"
edit_throttle_ms = 500
thread_replies = true

Events API Mode

If you prefer webhook-based delivery instead of Socket Mode:

[channels.slack.my-bot]
bot_token = "xoxb-..."
connection_mode = "events_api"
signing_secret = "abc123..."

This requires your Moltis instance to be reachable from the internet (or use Tailscale Funnel).

Access Control

Slack uses the same gating system as Telegram, Discord, and other channels.

DM Policy

Group Policy

Mention Mode

Allowlist Matching

Allowlist entries support:

• Exact match (case-insensitive): "U0123456789"
• Glob wildcards: "U012*", "*admin*"

Streaming

Slack supports three streaming modes:

The edit_in_place mode throttles updates to edit_throttle_ms milliseconds (default: 500) to avoid Slack API rate limits.

Thread Replies

By default (thread_replies = true), the bot replies in a thread attached to the user’s message. Set thread_replies = false to have the bot reply directly in the channel.

Troubleshooting

Bot doesn’t respond

• Verify the bot and app tokens are correct
• Check that Socket Mode is enabled in the Slack app settings
• Check dm_policy — if set to "allowlist", make sure your Slack user ID is in allowlist
• Ensure the bot has been invited to channels you want it to respond in
• Look at logs: RUST_LOG=moltis_slack=debug moltis

Bot doesn’t respond in channels

• Check mention_mode — if "mention", you must @mention the bot
• Check group_policy — if "disabled", channel messages are ignored
• Check channel_allowlist — if non-empty, the channel must be listed
• Ensure the bot is a member of the channel (invite it with /invite @botname)

WhatsApp Channel

Moltis supports WhatsApp as a messaging channel using the WhatsApp Linked Devices protocol. Your WhatsApp account connects as a linked device (like WhatsApp Web), so no separate phone number or WhatsApp Business API is needed — you pair your existing personal or business WhatsApp by scanning a QR code.

How It Works

┌────────────────┐   QR pair   ┌─────────────────┐   Signal   ┌──────────────┐
│  Your Phone    │ ──────────► │  Moltis Gateway  │ ◄────────► │  WhatsApp    │
│  (WhatsApp)    │             │  (linked device)  │            │  Servers     │
└────────────────┘             └─────────────────┘            └──────────────┘
                                       │
                                       ▼
                               ┌─────────────────┐
                               │  LLM Provider    │
                               │  (Claude, GPT…)  │
                               └─────────────────┘

1. Moltis registers as a linked device on your WhatsApp account
2. Messages sent to your WhatsApp number arrive at both your phone and Moltis
3. Moltis processes inbound messages through the configured LLM
4. The LLM reply is sent back through your WhatsApp account

Feature Flag

WhatsApp is behind the whatsapp cargo feature, enabled by default:

# crates/cli/Cargo.toml
[features]
default = ["whatsapp", ...]
whatsapp = ["moltis-gateway/whatsapp"]

When disabled, all WhatsApp code is compiled out — no QR code library, no Signal Protocol store, no WhatsApp event handlers.

Quick Start (Web UI)

The fastest way to connect WhatsApp:

1. Start Moltis: moltis serve
2. Open the web UI and navigate to Settings > Channels
3. Click + Add Channel > WhatsApp
4. Enter an Account ID (any name you like, e.g. my-whatsapp)
5. Choose a DM Policy (Open, Allowlist, or Disabled)
6. Optionally select a default Model
7. Click Start Pairing — a QR code appears
8. On your phone: WhatsApp > Settings > Linked Devices > Link a Device
9. Scan the QR code
10. The modal shows “Connected” with your phone’s display name

That’s it — messages to your WhatsApp account are now processed by Moltis.

Quick Start (Config File)

You can also configure WhatsApp accounts in moltis.toml. This is useful for automated deployments or when you want to pre-configure settings before pairing.

# ~/.moltis/moltis.toml

[channels.whatsapp."my-whatsapp"]
dm_policy = "open"
model = "anthropic/claude-sonnet-4-20250514"
model_provider = "anthropic"

Start Moltis and the account will begin the pairing process. The QR code is printed to the terminal and also available via the web UI. Once paired, the config file is updated with:

[channels.whatsapp."my-whatsapp"]
paired = true
display_name = "John's iPhone"
phone_number = "+15551234567"
dm_policy = "open"
model = "anthropic/claude-sonnet-4-20250514"
model_provider = "anthropic"

Configuration Reference

Each WhatsApp account is a named entry under [channels.whatsapp]:

[channels.whatsapp."<account-id>"]

Full Example

[channels.whatsapp."personal"]
paired = true
display_name = "John's iPhone"
phone_number = "+15551234567"
model = "anthropic/claude-sonnet-4-20250514"
model_provider = "anthropic"
dm_policy = "allowlist"
allowlist = ["alice", "bob", "+15559876543"]
group_policy = "disabled"
otp_self_approval = true
otp_cooldown_secs = 300

[channels.whatsapp."work-bot"]
paired = true
dm_policy = "open"
group_policy = "allowlist"
group_allowlist = ["120363456789@g.us"]
model = "openai/gpt-4.1"
model_provider = "openai"

Access Control

WhatsApp uses the same access control model as Telegram channels.

DM Policies

Group Policies

OTP Self-Approval

When dm_policy = "allowlist" and otp_self_approval = true (the default), users not on the allowlist can request access:

1. User sends any message to the bot
2. Bot replies: “Please reply with the 6-digit code to verify access”
3. The OTP code appears in the Senders tab of the web UI
4. User replies with the code
5. If correct, user is permanently added to the allowlist

After 3 wrong attempts, a cooldown period kicks in (default 5 minutes). You can also approve or deny users directly from the Senders tab without waiting for OTP verification.

Using Your Personal Number Safely

When Moltis is linked to your personal WhatsApp, it sees every incoming message — from friends, family, groups, everyone. The key question is: who does the bot respond to?

Self-chat always works. Messages you send to yourself (via “Message Yourself”) bypass access control entirely. You are the account owner, so you’re always authorized regardless of dm_policy settings.

Other people’s messages follow dm_policy. If you want Moltis to only respond to your self-chat and ignore everyone else:

[channels.whatsapp."personal"]
dm_policy = "disabled"    # Ignore all DMs from other people
group_policy = "disabled" # Ignore all group messages

This is the safest configuration for personal use — the bot only responds when you message yourself.

If you want to selectively allow certain contacts:

[channels.whatsapp."personal"]
dm_policy = "allowlist"
allowlist = ["alice", "bob"]  # Only these people get bot responses
group_policy = "disabled"

Session Persistence

WhatsApp uses the Signal Protocol for end-to-end encryption. The encryption keys and session state are stored in a sled database at:

~/.moltis/whatsapp/<account_id>/

This means:

• No re-pairing after restart — the linked device session survives process restarts, server reboots, and upgrades
• One store per account — multiple WhatsApp accounts each get their own isolated database
• Custom path — set store_path in config to use a different location (useful for Docker volumes or shared storage)

Self-Chat

Moltis automatically supports WhatsApp’s “Message Yourself” feature. When you send a message to yourself, the bot processes it as a regular inbound message and replies in the same chat.

This is useful for:

• Personal assistant — chat with your AI without a dedicated phone number
• Testing — verify the bot works before sharing with others
• Quick notes — send yourself reminders that the AI processes

Loop Prevention

When the bot replies to your self-chat, WhatsApp delivers that reply back as an incoming message (since it’s your own chat). Moltis uses two mechanisms to prevent infinite reply loops:

1. Message ID tracking: Every message the bot sends is recorded in a bounded ring buffer (256 entries). Incoming is_from_me messages whose ID matches a tracked send are recognized as bot echoes and skipped.

2. Invisible watermark: An invisible Unicode sequence (zero-width joiners) is appended to every bot-sent text message. If an incoming message contains this watermark, it’s recognized as a bot echo even if the message ID wasn’t tracked (e.g. after a restart).

Both checks are automatic — no configuration needed.

Media Handling

WhatsApp supports rich media messages. Moltis handles each type:

Managing Channels in the Web UI

Channels Tab

The Channels page shows all connected accounts across all channel types (Telegram, WhatsApp). Each card displays:

• Status badge: connected, pairing, or disconnected
• Display name: Phone name from WhatsApp (after pairing)
• Sender summary: List of recent senders with message counts
• Edit / Remove buttons

Adding a WhatsApp Channel

1. Click + Add Channel > WhatsApp
2. Fill in the account ID, DM policy, and optional model
3. Click Start Pairing
4. Scan the QR code on your phone
5. Wait for the “Connected” confirmation

Editing a Channel

Click Edit on a channel card to modify:

• DM and group policies
• Allowlist entries
• Default model

Changes take effect immediately — no restart needed.

Senders Tab

Switch to the Senders tab to see everyone who has messaged the bot:

• Filter by account using the dropdown
• See message counts, last activity, and access status
• Approve or Deny users directly
• View pending OTP challenges with the code displayed

Troubleshooting

WhatsApp Not in Add Channel Menu

• WhatsApp is not offered by default. Add "whatsapp" to the offered list in moltis.toml:

  [channels]
  offered = ["telegram", "discord", "slack", "whatsapp"]
  

• Restart Moltis after changing this setting

“Can’t Understand That Message Type”

• This means the bot received a message type it doesn’t handle (e.g. stickers, reactions, polls)
• Check the server logs for an info entry that lists which message fields were present
• Supported types: text, images, audio, voice notes, video, documents, and locations

QR Code Not Appearing

• Ensure the whatsapp feature is enabled (it is by default)
• Check terminal output for errors — the QR code is also printed to stdout
• Verify the sled store directory is writable: ~/.moltis/whatsapp/

“Logged Out” After Restart

• This usually means the sled store was corrupted or deleted
• Check that ~/.moltis/whatsapp/<account_id>/ exists and has data files
• Re-pair by removing the directory and restarting: the pairing flow starts again

Bot Not Responding to Messages

• Check dm_policy — if set to allowlist, only listed users get responses
• Check group_policy — if set to disabled, group messages are ignored
• Look at the Senders tab to see if the user is denied or pending OTP
• Check terminal logs for access control decisions

Self-Chat Not Working

• WhatsApp’s “Message Yourself” chat must be used (not a group with only yourself)
• The bot needs to be connected and the account paired
• If you just restarted, the watermark-based detection handles messages that arrive before the message ID buffer is rebuilt

Code Structure

crates/whatsapp/
├── src/
│   ├── lib.rs           # Crate entry, WhatsAppPlugin
│   ├── config.rs        # WhatsAppAccountConfig
│   ├── connection.rs    # Bot startup, sled store, event loop
│   ├── handlers.rs      # Event routing, message handling, media
│   ├── outbound.rs      # WhatsAppOutbound (ChannelOutbound impl)
│   ├── state.rs         # AccountState, loop detection, watermark
│   ├── access.rs        # DM/group access control
│   ├── otp.rs           # OTP challenge/verification
│   ├── plugin.rs        # ChannelPlugin trait impl
│   ├── sled_store.rs    # Persistent Signal Protocol store
│   └── memory_store.rs  # In-memory store (tests/fallback)

Browser Automation

Moltis provides full browser automation via Chrome DevTools Protocol (CDP), enabling agents to interact with JavaScript-heavy websites, fill forms, click buttons, and capture screenshots.

Overview

Browser automation is useful when you need to:

• Interact with SPAs (Single Page Applications)
• Fill forms and click buttons
• Navigate sites that require JavaScript rendering
• Take screenshots of pages
• Execute JavaScript in page context
• Maintain session state across multiple interactions

For simple page content retrieval (static HTML), prefer web_fetch as it’s faster and more lightweight.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌──────────────────┐
│   BrowserTool   │────▶│  BrowserManager │────▶│   BrowserPool    │
│   (AgentTool)   │     │   (actions)     │     │   (instances)    │
└─────────────────┘     └─────────────────┘     └──────────────────┘
                                                         │
                                                         ▼
                                                ┌──────────────────┐
                                                │  Chrome/Chromium │
                                                │     via CDP      │
                                                └──────────────────┘

Components

• BrowserTool (crates/tools/src/browser.rs) - AgentTool wrapper for LLM
• BrowserManager (crates/browser/src/manager.rs) - High-level action API
• BrowserPool (crates/browser/src/pool.rs) - Chrome instance management
• Snapshot (crates/browser/src/snapshot.rs) - DOM element extraction

Configuration

Browser automation is enabled by default. To customize, add to your moltis.toml:

[tools.browser]
enabled = true              # Enable browser support
headless = true             # Run without visible window (default)
viewport_width = 2560       # Default viewport width
viewport_height = 1440      # Default viewport height
device_scale_factor = 2.0   # HiDPI/Retina scaling (1.0 = standard, 2.0 = Retina)

# Pool management
max_instances = 0           # 0 = unlimited (limited by memory), >0 = hard limit
memory_limit_percent = 90   # Block new instances when memory exceeds this %
idle_timeout_secs = 300     # Close idle browsers after 5 min
navigation_timeout_ms = 30000  # Page load timeout

# Optional customization
# chrome_path = "/path/to/chrome"  # Custom Chrome path
# user_agent = "Custom UA"         # Custom user agent
# chrome_args = ["--disable-extensions"]  # Extra args

# Sandbox image (browser sandbox mode follows session sandbox mode)
sandbox_image = "browserless/chrome"  # Container image for sandboxed sessions
# allowed_domains = ["example.com", "*.trusted.org"]  # Restrict navigation

# Container connectivity (for Moltis-in-Docker setups)
# container_host = "127.0.0.1"  # Default; change when Moltis runs inside Docker

Memory-Based Pool Limits

By default, browser instances are limited by system memory rather than a fixed count:

• max_instances = 0 (default): Unlimited instances, blocked only when memory exceeds memory_limit_percent
• memory_limit_percent = 90: New browsers blocked when system memory > 90%
• Set max_instances > 0 for a hard limit if you prefer fixed constraints

This allows multiple chat sessions to each have their own browser without artificial limits, while protecting system stability when memory is constrained.

Domain Restrictions

For improved security, you can restrict which domains the browser can navigate to:

[tools.browser]
allowed_domains = [
    "docs.example.com",    # Exact match
    "*.github.com",        # Wildcard: matches any subdomain
    "localhost",           # Allow localhost
]

When allowed_domains is set, any navigation to a domain not in the list will be blocked with an error. Wildcards (*.domain.com) match any subdomain and also the base domain itself.

Tool Usage

Actions

Automatic Session Tracking

The browser tool automatically tracks and reuses session IDs. After a navigate action creates a session, subsequent actions will reuse it without needing to pass session_id explicitly:

// 1. Navigate (creates session)
{ "action": "navigate", "url": "https://example.com" }

// 2. Snapshot (session_id auto-injected)
{ "action": "snapshot" }

// 3. Click (session_id auto-injected)
{ "action": "click", "ref_": 1 }

// 4. Screenshot (session_id auto-injected)
{ "action": "screenshot" }

// 5. Close (clears tracked session)
{ "action": "close" }

This prevents pool exhaustion from LLMs that forget to pass the session_id.

Browser selection

You can ask for a specific browser at runtime (host mode):

{ "action": "navigate", "url": "https://example.com", "browser": "brave" }

Supported values: auto, chrome, chromium, edge, brave, opera, vivaldi, arc.

auto (default) picks the first detected installed browser. If none are installed, Moltis will attempt a best-effort auto-install, then retry detection.

Workflow Example

// 1. Navigate to a page
{
  "action": "navigate",
  "url": "https://example.com/login"
}
// Returns: { "session_id": "browser-abc123", "url": "https://..." }

// 2. Get interactive elements (session_id optional - auto-tracked)
{
  "action": "snapshot"
}
// Returns element refs like:
// { "elements": [
//   { "ref_": 1, "tag": "input", "role": "textbox", "placeholder": "Email" },
//   { "ref_": 2, "tag": "input", "role": "textbox", "placeholder": "Password" },
//   { "ref_": 3, "tag": "button", "role": "button", "text": "Sign In" }
// ]}

// 3. Fill in the form
{
  "action": "type",
  "ref_": 1,
  "text": "user@example.com"
}

{
  "action": "type",
  "ref_": 2,
  "text": "password123"
}

// 4. Click the submit button
{
  "action": "click",
  "ref_": 3
}

// 5. Take a screenshot of the result
{
  "action": "screenshot"
}
// Returns: { "screenshot": "data:image/png;base64,..." }

Element Reference System

The snapshot action extracts interactive elements and assigns them numeric references. This approach (inspired by OpenClaw) provides:

• Stability: References don’t break with minor page updates
• Security: No CSS selectors exposed to the model
• Reliability: Elements identified by role/content, not fragile paths

Extracted Element Info

{
  "ref_": 1,
  "tag": "button",
  "role": "button",
  "text": "Submit",
  "href": null,
  "placeholder": null,
  "value": null,
  "aria_label": "Submit form",
  "visible": true,
  "interactive": true,
  "bounds": { "x": 100, "y": 200, "width": 80, "height": 40 }
}

Comparison: Browser vs Web Fetch

When to use web_fetch:

• Reading documentation
• Fetching API responses
• Scraping static HTML

When to use browser:

• Logging into websites
• Filling forms
• Interacting with SPAs
• Sites that require JavaScript
• Taking screenshots

Metrics

When the metrics feature is enabled, the browser module records:

Sandbox Mode

Browser sandbox mode automatically follows the session’s sandbox mode. When a chat session uses sandbox mode (controlled by [tools.exec.sandbox]), the browser tool will also run in a sandboxed container. When the session is not sandboxed, the browser runs directly on the host.

Host Mode

When the session is not sandboxed (or sandbox mode is “off”), Chrome runs directly on the host machine. This is faster but the browser has full access to the host network and filesystem.

Sandbox Mode

When the session is sandboxed, Chrome runs inside a Docker container with:

• Network isolation: Browser can access the internet but not local services
• Filesystem isolation: No access to host filesystem
• Automatic lifecycle: Container started/stopped with browser session
• Readiness detection: Waits for Chrome to be fully ready before connecting

[tools.browser]
sandbox_image = "browserless/chrome"  # Container image for sandboxed sessions

Requirements:

• Docker or Apple Container must be installed and running
• The container image is pulled automatically on first use
• Session sandbox mode must be enabled ([tools.exec.sandbox] mode = "all")

Moltis Inside Docker (Sibling Containers)

When Moltis itself runs inside a Docker container, the browser container is launched as a sibling via the host’s Docker socket. By default Moltis connects to the browser at 127.0.0.1, which points to the Moltis container’s own loopback — not the host where the browser port is mapped.

Set container_host so Moltis can reach the browser container through the host’s port mapping:

[tools.browser]
container_host = "host.docker.internal"   # macOS / Windows Docker Desktop
# container_host = "172.17.0.1"           # Linux Docker bridge gateway IP

On Linux, host.docker.internal is not available by default. Use the Docker bridge gateway IP (typically 172.17.0.1) or add --add-host=host.docker.internal:host-gateway to the Moltis container’s docker run command.

Exec Tool Scripts

If agents need to run browser automation scripts (Puppeteer, Playwright, Selenium) inside the command sandbox, Chromium is included in the default sandbox packages:

# Inside sandbox (via exec tool)
chromium --headless --no-sandbox --dump-dom https://example.com

Or use Puppeteer/Playwright in a Node.js script executed via the exec tool.

Security Considerations

Prompt Injection Risk

Important: Web pages can contain content designed to manipulate LLM behavior (prompt injection). When the browser tool returns page content to the LLM, malicious sites could attempt to inject instructions.

Mitigations:

1. Domain restrictions: Use allowed_domains to limit navigation to trusted sites only. This is the most effective mitigation.

2. Review returned content: The snapshot action returns element text which could contain injected prompts. Be cautious with untrusted sites.

3. Sandbox mode: Use sandboxed sessions to run the browser in an isolated Docker container for additional security. Browser sandbox follows session sandbox mode automatically.

Other Security Considerations

1. Host vs Sandbox mode: Browser sandbox mode follows the session’s sandbox mode. For sandboxed sessions, the browser runs in a Docker container with network/filesystem isolation. For non-sandboxed sessions, the browser runs on the host with --no-sandbox for container compatibility.

2. Resource limits: Browser instances are limited by memory usage (default: block when > 90% used). Set max_instances > 0 for a hard limit.

3. Idle cleanup: Browsers are automatically closed after idle_timeout_secs of inactivity.

4. Network access: In host mode, the browser has full network access. In sandbox mode, the browser can reach the internet but not local services. Use firewall rules for additional restrictions.

5. Sandbox scripts: Browser scripts running in the exec sandbox (Puppeteer, Playwright) inherit sandbox network restrictions (no_network: true by default).

Browser Detection

Moltis automatically detects installed Chromium-based browsers in the following order:

1. Custom path from chrome_path config
2. CHROME environment variable
3. Platform-specific app bundles (macOS/Windows)
   • macOS: /Applications/Google Chrome.app, /Applications/Chromium.app, etc.
   • Windows: C:\Program Files\Google\Chrome\Application\chrome.exe, etc.
4. PATH executables (fallback): chrome, chromium, msedge, brave, etc.

If no browser is found, Moltis displays platform-specific installation instructions.

Supported Browsers

Any Chromium-based browser works:

• Google Chrome
• Chromium
• Microsoft Edge
• Brave
• Opera
• Vivaldi
• Arc (macOS)

Screenshot Display

When the browser tool takes a screenshot, it’s displayed in the chat UI:

• Thumbnail view: Screenshots appear as clickable thumbnails (200×150px max)
• Fullscreen lightbox: Click to view full-size with dark overlay
• Scrollable view: Long screenshots can be scrolled within the lightbox
• Download button: Save screenshot to disk (top of lightbox)
• Close button: Click ✕ button, click outside, or press Escape to close
• HiDPI scaling: Screenshots display at correct size on Retina displays

Screenshots are base64-encoded PNGs returned in the tool result. The device_scale_factor config (default: 2.0) controls the rendering resolution for high-DPI displays.

Telegram Integration

When using the Telegram channel, screenshots are automatically sent to the chat:

• Images sent as photos when dimensions are within Telegram limits
• Automatically retried as documents for oversized images (aspect ratio > 20)
• Error messages sent to channel if delivery fails

Handling Model Errors

Some models (particularly Claude via GitHub Copilot) occasionally send malformed tool calls with missing required fields. Moltis handles this gracefully:

• Default action: If url is provided but action is missing, defaults to navigate
• Automatic retry: The agent loop retries with corrected arguments
• Muted error display: Validation errors show as muted/informational cards in the UI (60% opacity, gray text) to indicate they’re expected, not alarming

Troubleshooting

Browser not launching

• Ensure Chrome/Chromium is installed
• Check chrome_path in config if using custom location
• Set CHROME environment variable to specify browser path
• On Linux, install dependencies: apt-get install chromium-browser
• On macOS, if using Homebrew Chromium, prefer installing Google Chrome or Brave (the Homebrew chromium wrapper can be unreliable)

Elements not found

• Use snapshot to see available elements
• Elements must be visible in the viewport
• Some elements may need scrolling first

Timeouts

• Increase navigation_timeout_ms for slow pages
• Use wait action to wait for dynamic content
• Check network connectivity

High memory usage

• Browser instances are now limited by memory (blocks at 90% by default)
• Set max_instances > 0 for a hard limit if preferred
• Lower idle_timeout_secs to clean up faster
• Consider enabling headless mode if not already

Pool exhaustion

• Browser tool now auto-tracks session IDs, preventing pool exhaustion from LLMs that forget to pass session_id
• If you still hit limits, check memory_limit_percent threshold
• Use close action when done to free up sessions

CalDAV (Calendars)

Moltis can read and manage remote calendars through the CalDAV protocol. Once configured, the agent gains a caldav tool that can list calendars, query events, and create, update, or delete entries on your behalf.

The feature is compiled in by default (the caldav cargo feature) and can be disabled at build time with --no-default-features.

Configuration

Add a [caldav] section to your moltis.toml (usually ~/.moltis/moltis.toml):

[caldav]
enabled = true
default_account = "fastmail"

[caldav.accounts.fastmail]
provider = "fastmail"
username = "you@fastmail.com"
password = "app-specific-password"

Multiple accounts

You can define as many accounts as you like. When only one account exists it is used implicitly; otherwise specify default_account or pass account in each tool call.

[caldav]
enabled = true
default_account = "work"

[caldav.accounts.work]
provider = "fastmail"
username = "work@fastmail.com"
password = "app-specific-password"

[caldav.accounts.personal]
provider = "icloud"
username = "you@icloud.com"
password = "app-specific-password"

Supported providers

For generic servers, provide the CalDAV base URL:

[caldav.accounts.nextcloud]
provider = "generic"
url      = "https://cloud.example.com/remote.php/dav"
username = "admin"
password = "secret"

Account fields

How it works

When Moltis starts and CalDAV is enabled with at least one account, a caldav tool is registered in the agent tool registry. The agent can then call it during conversations to interact with your calendars.

Connections are established lazily on first use and cached for the lifetime of the process. All communication uses HTTPS with system-native TLS roots.

Operations

The agent calls the caldav tool with an operation parameter. Five operations are available:

list_calendars

Lists all calendars available on the account.

Returns: href, display_name, color, description for each calendar.

list_events

Lists events in a specific calendar, optionally filtered by date range.

Returns: href, etag, uid, summary, start, end, all_day, location for each event.

create_event

Creates a new calendar event.

Returns: href, etag, uid of the created event.

update_event

Updates an existing event. Uses ETag-based optimistic concurrency control to prevent overwriting concurrent changes.

Returns: updated href and etag.

delete_event

Deletes an event. Also requires the current ETag.

Concurrency control

Updates and deletes require an etag obtained from list_events. If the event was modified on the server since the ETag was fetched (e.g. edited from a phone), the server rejects the request with a conflict error. This prevents accidental overwrites. The agent should re-fetch the event and retry.

Example conversation

You: What’s on my calendar this week?

The agent calls list_calendars, picks the primary calendar, then calls list_events with start / end spanning the current week.

Agent: You have 3 events this week: …

You: Move the dentist appointment to Friday at 2pm.

The agent calls update_event with the event’s href and etag, setting the new start time.

Disabling CalDAV

Set enabled = false or remove the [caldav] section entirely:

[caldav]
enabled = false

To disable at compile time, build without the feature:

cargo build --release --no-default-features --features lightweight

Validation

moltis config check validates CalDAV configuration and warns about unknown providers. Valid provider values are: fastmail, icloud, generic.

GraphQL API

Moltis exposes a GraphQL API that mirrors gateway RPC methods with typed query and mutation responses where the data shape is known.

Availability

GraphQL is compile-time feature gated:

• Gateway feature: graphql
• CLI feature: graphql (enabled in default feature set)

If Moltis is built without this feature, /graphql is not registered.

When built with the feature, GraphQL is runtime-toggleable:

• Config: [graphql] enabled = true|false
• UI: Settings > GraphQL toggle

Changes apply immediately, without restart.

Endpoints

WebSocket subprotocols accepted:

• graphql-transport-ws
• graphql-ws

Authentication and Security

GraphQL is protected by the same auth decisions used elsewhere in the gateway. It is not on the public path allowlist.

• With web-ui builds, GraphQL is behind the global auth_gate middleware.
• Without web-ui, GraphQL is explicitly guarded by graphql_auth_gate.

When auth is required and the request is unauthenticated, GraphQL returns 401 ({"error":"not authenticated"} or {"error":"setup required"}).

When GraphQL is runtime-disabled, /graphql returns 503 ({"error":"graphql server is disabled"}).

Supported auth methods:

• Valid session cookie (moltis_session)
• Authorization: Bearer <api_key>

Schema Layout

The schema is organized by namespaces that map to gateway method groups.

Top-level query fields include:

• health
• status
• system, node, chat, sessions, channels
• config, cron, heartbeat, logs
• tts, stt, voice
• skills, models, providers, mcp
• usage, execApprovals, projects, memory, hooks, agents
• voicewake, device

Top-level mutation fields follow the same namespace pattern (for example: chat.send, config.set, cron.add, providers.oauthStart, mcp.reauth).

Subscriptions include:

• chatEvent
• sessionChanged
• cronNotification
• channelEvent
• nodeEvent
• tick
• logEntry
• mcpStatusChanged
• approvalEvent
• configChanged
• presenceChanged
• metricsUpdate
• updateAvailable
• voiceConfigChanged
• skillsInstallProgress
• allEvents

Typed Data and Json Scalar

Most GraphQL return types are concrete structs. The custom Json scalar is still used where runtime shape is intentionally dynamic (for example: arbitrary config values, context payloads, or pass-through node payloads).

Examples

Query (health)

curl -sS http://localhost:13131/graphql \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer mk_your_api_key' \
  -d '{"query":"{ health { ok connections } }"}'

Query with namespace fields

query {
  status {
    hostname
    version
    connections
  }
  cron {
    list {
      id
      name
      enabled
    }
  }
}

Mutation

mutation {
  chat {
    send(message: "Hello from GraphQL") {
      ok
      sessionKey
    }
  }
}

Subscription (graphql-transport-ws)

1. Connect to ws://localhost:13131/graphql with subprotocol graphql-transport-ws.
2. Send:

{ "type": "connection_init" }

3. Start a subscription:

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription { tick { ts connections } }"
  }
}

GraphiQL in the Web UI

When the binary includes GraphQL, the Settings page includes a GraphQL tab. At the top of that page you can enable/disable GraphQL immediately; when enabled it embeds GraphiQL at /graphql.

Session State

Moltis provides a per-session key-value store that allows skills, extensions, and the agent itself to persist context across messages within a session.

Overview

Session state is scoped to a (session_key, namespace, key) triple, backed by SQLite. Each entry stores a string value and is automatically timestamped.

The agent accesses state through the session_state tool, which supports three operations: get, set, and list.

Agent Tool

The session_state tool is registered as a built-in tool and available in every session.

Get a value

{
  "op": "get",
  "namespace": "my-skill",
  "key": "last_query"
}

Set a value

{
  "op": "set",
  "namespace": "my-skill",
  "key": "last_query",
  "value": "SELECT * FROM users"
}

List all keys in a namespace

{
  "op": "list",
  "namespace": "my-skill"
}

Namespacing

Every state entry belongs to a namespace. This prevents collisions between different skills or extensions using state in the same session. Use your skill name as the namespace.

Storage

State is stored in the session_state table in the main SQLite database (moltis.db). The migration is in crates/sessions/migrations/20260205120000_session_state.sql.

Session Branching

Session branching (forking) lets you create an independent copy of a conversation at any point. The new session diverges without affecting the original — useful for exploring alternative approaches, running “what if” scenarios, or preserving a checkpoint before a risky prompt.

Forking from the UI

There are two ways to fork a session in the web UI:

• Chat header — click the Fork button in the header bar (next to Delete). This is visible for every session except cron sessions.
• Sidebar — hover over a session in the sidebar and click the fork icon that appears in the action buttons.

Both create a new session that copies all messages from the current one and immediately switch you to it.

Forked sessions appear indented under their parent in the sidebar, with a branch icon to distinguish them from top-level sessions. The metadata line shows fork@N where N is the message index at which the fork occurred.

Agent Tool

The agent can also fork programmatically using the branch_session tool:

{
  "at_message": 5,
  "label": "explore-alternative"
}

• at_message — the message index to fork at (messages 0..N are copied). If omitted, all messages are copied.
• label — optional human-readable label for the new session.

The tool returns the new session key.

RPC Method

The sessions.fork RPC method is the underlying mechanism:

{ "key": "main", "at_message": 5, "label": "my-fork" }

On success the response payload contains { "sessionKey": "session:<uuid>" }.

What Gets Inherited

When forking, the new session inherits:

Parent-Child Relationships

Fork relationships are stored directly on the sessions table:

• parent_session_key — the key of the session this was forked from.
• fork_point — the message index where the fork occurred.

These fields drive the tree rendering in the sidebar. Sessions with a parent appear indented under it; deeply nested forks indent further.

Navigation After Delete

When you delete a forked session, the UI navigates back to its parent session. If the deleted session had no parent (or the parent no longer exists), it falls back to the next sibling or main.

Scheduling (Cron Jobs)

Moltis includes a built-in cron system that lets the agent schedule and manage recurring tasks. Jobs can fire agent turns, send system events, or trigger other actions on a flexible schedule.

Heartbeat

The heartbeat is a special system cron job (__heartbeat__) that runs periodically (default: every 30 minutes). It gives the agent an opportunity to check reminders, run deferred tasks, and react to events that occurred while the user was away.

The heartbeat prompt is assembled from HEARTBEAT.md in the workspace data directory. If the file is empty and no pending events exist, the heartbeat turn is skipped to save tokens.

Heartbeat replies can also be delivered to a configured channel destination via [heartbeat] deliver, channel, and to in moltis.toml, or from the web UI under Settings -> Heartbeat.

Event-Driven Heartbeat Wake

Normally the heartbeat fires on its regular schedule. The wake system lets other parts of Moltis trigger an immediate heartbeat when something noteworthy happens, so the agent can react in near real-time.

Wake Mode

Every cron job has a wakeMode field that controls whether it triggers an immediate heartbeat after execution:

Set wakeMode when creating or updating a job through the cron tool:

{
  "action": "add",
  "job": {
    "name": "check-deploy",
    "schedule": { "kind": "every", "every_ms": 300000 },
    "payload": { "kind": "agentTurn", "message": "Check deploy status" },
    "wakeMode": "now"
  }
}

Aliases are accepted: "immediate", "immediately" map to "now"; "next", "default", "next_heartbeat", "next-heartbeat" map to "nextHeartbeat".

System Events Queue

Moltis maintains an in-memory bounded queue of system events — short text summaries of things that happened (command completions, cron triggers, etc.). When the heartbeat fires, any pending events are drained from the queue and prepended to the heartbeat prompt so the agent sees what occurred.

The queue holds up to 20 events. Consecutive duplicate events are deduplicated. Events that arrive after the buffer is full are silently dropped (oldest events are preserved).

Exec Completion Events

When a background command finishes (via the exec tool), Moltis automatically enqueues a summary event with the command name, exit code, and a short preview of stdout/stderr. If the heartbeat is idle, it is woken immediately so the agent can react to the result.

This means the agent learns about completed background tasks without polling — a long-running build or deployment that finishes while the user is away will surface in the next heartbeat turn.

Schedule Types

Jobs support several schedule kinds:

Cron Tool

The agent manages jobs through the built-in cron tool. Available actions:

• add — Create a new job
• list — List all jobs
• run — Trigger a job immediately
• update — Patch an existing job (name, schedule, enabled, wakeMode, etc.)
• remove — Delete a job
• runs — View recent execution history for a job

One-Shot Jobs

Set deleteAfterRun: true to automatically remove a job after its first execution. Combined with the at schedule, this is useful for deferred one-time tasks (reminders, follow-ups).

Channel Delivery

Background agent turns can deliver their final output to a configured channel account/chat after the run completes.

Use all of the following together:

• sessionTarget: "isolated"
• payload.kind: "agentTurn"
• payload.deliver: true
• payload.channel: "<account_id>"
• payload.to: "<chat_or_peer_id>"

Example:

{
  "action": "add",
  "job": {
    "name": "daily summary",
    "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Europe/Paris" },
    "sessionTarget": "isolated",
    "payload": {
      "kind": "agentTurn",
      "message": "Summarize yesterday's activity and send it to Telegram.",
      "deliver": true,
      "channel": "my-telegram-bot",
      "to": "123456789"
    }
  }
}

Channel delivery is separate from session targeting. The cron job still runs in an isolated cron session, then Moltis forwards the finished output to the requested channel destination.

Session Targeting

Each job specifies where its agent turn runs:

Security

See Cron Job Security for rate limiting, sandbox isolation, and job notification details.

Metrics