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
• Cross-Session Recall — Search earlier sessions for relevant snippets and prior decisions
• Automatic Checkpoints — Restore built-in skill and memory mutations without touching git history
• Remote Exec Targets — Route command execution locally, through a paired node, or over SSH
• Context Hardening — Load CLAUDE.md, AGENTS.md, .cursorrules, and rule directories with safety scanning
• 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

Package filenames are versioned on every release. Use the installer script below instead of hardcoding GitHub release asset names.

Debian / Ubuntu (.deb)

# Install the latest .deb package
curl -fsSL https://www.moltis.org/install.sh | sh -s -- --method=deb

Fedora / RHEL (.rpm)

# Install the latest .rpm package
curl -fsSL https://www.moltis.org/install.sh | sh -s -- --method=rpm

Arch Linux (.pkg.tar.zst)

# Install the latest package
curl -fsSL https://www.moltis.org/install.sh | sh -s -- --method=arch

Snap

sudo snap install moltis

AppImage

# Install the latest AppImage
curl -fsSL https://www.moltis.org/install.sh | sh -s -- --method=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 the larger open-source personal agent projects: OpenClaw and Hermes Agent.

Disclaimer: This page is based on source snapshots captured while writing: OpenClaw 90eb5b0 from 2026-04-01, Hermes Agent 9f22977 from 2026-04-20, and Moltis 5d044c6 from 2026-04-22. Projects move quickly, so check each repository for current behavior before making a deployment decision.

At a Glance

* LoC measured with tokei, excluding node_modules, generated build output, dist, and target. Counts are a rough auditability signal, not a quality metric.

Architecture Approach

OpenClaw, ecosystem-first personal assistant

OpenClaw is a full-featured personal assistant platform. The local checkout shows a TypeScript gateway with macOS, iOS, and Android companion surfaces, plus a large channel list, node tools, browser/canvas support, plugin extensions, onboarding, and managed/workspace skills.

Hermes Agent, learning-loop CLI and gateway

Hermes Agent is Python-first. Its README centers the agent around a terminal interface, a messaging gateway, a closed learning loop, self-improving skills, agent-curated memory, session search, user modeling, cron scheduling, and cloud/serverless execution backends. Moltis has autonomous skill improvement too, so Hermes’ sharper distinction is its CLI/research loop and broad terminal backend set. It also carries research-oriented pieces such as trajectory generation and RL environments.

Moltis, Rust-native persistent agent server

Moltis prioritizes a smaller trusted runtime, durable agent workflows, and defense in depth. The Rust workspace is currently ~270K lines across 59 crates. The agent runner and model interface are ~7.5K lines, with provider implementations in ~19K more.

Key differences:

• Single Rust binary instead of a Node.js or Python application runtime
• Built-in web UI with streaming chat, settings, sessions, projects, and admin surfaces
• Docker/Podman, Apple Container, and WASM sandboxing
• Password, WebAuthn passkeys, scoped API keys, and vault-backed secret storage
• Cross-session recall without dumping raw history into every prompt
• Autonomous skill self-improvement with enable_self_improvement on by default
• Automatic checkpoints before built-in skill and memory mutations
• 15 lifecycle hook events with circuit breaker and dry-run mode
• Read-only OpenClaw import for identity, providers, skills, memory, sessions, channels, and MCP config

Moltis intentionally has a small unsafe surface, not a zero-unsafe entire workspace. Unsafe code is isolated to Swift FFI, local model wrappers, and precompiled WASM/runtime boundaries. The core agent and gateway paths stay in safe Rust.

Security Model

Local Checkout Snapshot

* These counts are intentionally limited to app/source directories and exclude dependency folders and build output. They are useful for spotting scale, not for ranking projects.

Links

• OpenClaw and OpenClaw docs
• Hermes Agent and Hermes docs
• Moltis and Moltis docs

Configuration

Moltis uses a layered config model with two files:

On first run, both files are created in ~/.config/moltis/. Your moltis.toml starts nearly empty — only the installation-specific port is set. All other settings inherit from defaults.toml automatically.

Merge Order

Settings are resolved in this order (later wins):

1. Built-in defaults — compiled into Moltis (MoltisConfig::default())
2. defaults.toml — Moltis-managed, refreshed on every startup
3. moltis.toml — your overrides (additive deep merge)
4. MOLTIS_* environment variables — highest precedence

This means you only need to put values in moltis.toml that you intentionally want to differ from the shipped defaults. When Moltis upgrades and improves a default, your installation picks it up automatically — unless you’ve overridden that specific setting.

Configuration File Location

The defaults.toml file lives in the same directory. Do not edit it — your changes will be overwritten on the next startup.

Checking Config

moltis config check validates your override file (moltis.toml) against the known config schema. It also checks that Moltis-managed defaults.toml exists and can be parsed, but it does not treat defaults.toml as user-authored input.

New config fields should be added to the Rust config schema and its Default implementation. Moltis regenerates defaults.toml from those built-in defaults on startup, while moltis.toml should contain only values you intentionally override.

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.

Remote Execution

Command execution can stay local, route to a paired node, or use SSH:

[tools.exec]
host = "local"                 # "local", "node", or "ssh"
# node = "mac-mini"            # default paired node when host = "node"
# ssh_target = "deploy@box"    # default SSH target when host = "ssh"

When host = "ssh", Moltis can work in two modes:

• System OpenSSH: reuse your existing host aliases, agent forwarding policy, and ~/.ssh/config.
• Managed targets: create or import a deploy key in Settings → SSH, then bind that key to a named target. Moltis stores the private key in its credential store and encrypts it with the vault whenever the vault is unsealed. Imported keys may be passphrase-protected, Moltis strips the passphrase during import so runtime execution can stay non-interactive.

For stricter SSH verification, managed targets also accept a pasted known_hosts line from ssh-keyscan -H host. The SSH settings page can scan that for you, and saved targets can refresh or clear their stored pin later. When present, Moltis uses that pin instead of your global OpenSSH known-host policy for that target.

Managed targets appear in the Nodes page and chat node picker, so users can see where exec will run without digging through config. If multiple managed targets exist, the default one is used when tools.exec.host = "ssh" and no session-specific route is selected. moltis doctor also reports remote-exec inventory, active backend mode, and obvious SSH setup problems from the CLI.

Settings -> Tools shows the effective tool inventory for the active session and model, including tool-calling support, MCP server state, skills/plugins, and available execution routes. It is session-aware by design, switching the model or disabling MCP for a session changes what appears there.

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_self_improvement = true     # System prompt guidance for autonomous skill creation/update

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.

enable_self_improvement (default: true) injects system prompt guidance that encourages the agent to proactively create and update skills after complex tasks (5+ tool calls), tricky error fixes, or non-obvious workflows. The patch_skill tool allows surgical find/replace updates without rewriting the entire skill body.

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
prompt_memory_mode = "live-reload"

# Options:
#   "followup" - Queue each message and run them sequentially
#   "collect"  - Merge queued text and run once after the active run
#   "live-reload" - Re-read MEMORY.md before each turn
#   "frozen-at-session-start" - Keep the first MEMORY.md snapshot for the session

Memory System

Long-term memory uses embeddings for semantic search:

[memory]
style = "hybrid"              # Or "prompt-only", "search-only", "off"
agent_write_mode = "hybrid"   # Or "prompt-only", "search-only", "off"
user_profile_write_mode = "explicit-and-auto" # Or "explicit-only", "off"
backend = "builtin"             # Or "qmd"
provider = "openai"             # Or "local", "ollama", "custom"
model = "text-embedding-3-small"
citations = "auto"              # "on", "off", or "auto"
llm_reranking = false
search_merge_strategy = "rrf"   # Or "linear"
session_export = "on-new-or-reset" # Or "off"

See Memory Surfaces for the boundary between session_state, prompt memory, searchable memory, and sandbox persistence. memory.style chooses the high-level behavior, while chat.prompt_memory_mode only affects prompt-visible MEMORY.md. memory.agent_write_mode controls where agent-authored writes are allowed to land. memory.user_profile_write_mode controls whether Moltis writes the managed USER.md surface, and whether browser/channel timezone or location signals may update it silently. memory.session_export controls whether session rollover exports are written at all.

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}" }

[mcp.servers.remote_http]
transport = "streamable-http"
url = "https://mcp.example.com/mcp"
headers = { Authorization = "Bearer ${API_KEY}" }

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

Upstream Proxy

Moltis can route all outbound HTTP traffic through an upstream proxy. This is useful when running behind a corporate firewall, in a restricted network, or when you need to audit/filter outbound connections.

Configuration

Add upstream_proxy to the top level of your moltis.toml:

upstream_proxy = "http://proxy.corp.example.com:8080"

Supported schemes

Proxy authentication

Include credentials in the URL:

upstream_proxy = "http://user:password@proxy.corp.example.com:8080"

What is proxied

When upstream_proxy is set, the following traffic routes through the proxy:

• LLM provider API calls (Anthropic, OpenAI, Gemini, etc.)
• Tool HTTP requests (web fetch, web search, Firecrawl)
• OAuth flows (device auth, token exchange)
• MCP server auth (OAuth for remote MCP servers)
• Channel outbound (Slack streaming, MS Teams API calls)

Localhost and loopback addresses (127.0.0.1, ::1, localhost) are automatically excluded from the proxy (no_proxy).

Slack caveat

Slack streaming messages (progressive edits) are proxied via reqwest. However, regular chat.postMessage calls go through the slack-morphism library’s built-in hyper connector, which does not use the upstream proxy. If you need full Slack proxy coverage, also set the HTTPS_PROXY environment variable.

Telegram caveat

Telegram uses teloxide which bundles its own HTTP client (reqwest 0.11). The upstream_proxy config does not apply to Telegram traffic directly. To proxy Telegram, set the standard HTTPS_PROXY environment variable, which teloxide’s reqwest honours:

export HTTPS_PROXY=http://proxy.corp.example.com:8080
moltis

Or use the env section in moltis.toml:

[env]
HTTPS_PROXY = "http://proxy.corp.example.com:8080"

Environment variable fallback

When upstream_proxy is not set in moltis.toml, reqwest automatically honours the standard proxy environment variables:

• HTTP_PROXY / http_proxy
• HTTPS_PROXY / https_proxy
• ALL_PROXY / all_proxy
• NO_PROXY / no_proxy

Setting upstream_proxy in the config takes precedence over these variables for all traffic except Telegram (see caveat above).

Interaction with Trusted Network

If you use both upstream_proxy and trusted network mode (network = "trusted"), they serve different purposes:

• Trusted network proxy is a local domain-filtering proxy for sandbox tool execution. It controls which domains tools can reach.
• Upstream proxy routes traffic through your corporate/network proxy to reach the internet.

When both are active, tool traffic routes through the trusted-network proxy (which enforces domain allowlists), while provider and channel traffic routes through the upstream proxy.

Configuration Reference

Manually authored from source: crates/config/src/schema/ + crates/config/src/validate/schema_map.rs

Every valid moltis.toml option, organized by domain.

Types: string, bool, integer, float, array, map, optional, enum(...).

Defaults shown as TOML values. — means the field has no explicit default (uses Rust Default).

Contents

• Server & Networking
• Observability
• Identity & User
• Chat & Agents
• Tools — Execution
• Tools — Web & Data
• Tools — Policy & Agent Limits
• Channels & Integrations
• Memory
• Scheduling & Webhooks
• LLM Providers
• Voice — Text-to-Speech
• Voice — Speech-to-Text
• Environment
• Server & Networking
  • server
  • auth
  • tls
  • graphql
  • ngrok
  • tailscale
  • upstream_proxy
  • failover
• Observability
  • metrics
• Identity & User
  • identity
  • user
• Chat & Agents
  • chat
  • chat.compaction
  • agents
  • agents.presets.<name>
  • modes
  • modes.presets.<name>
  • skills
• Tools — Execution
  • tools.exec
  • tools.exec.sandbox
  • tools.exec.sandbox.resource_limits
  • tools.exec.sandbox.tools_policy
  • tools.exec.sandbox.wasm_tool_limits
  • tools.browser
• Tools — Web & Data
  • tools.web.search
  • tools.web.search.perplexity
  • tools.web.fetch
  • tools.web.firecrawl
  • tools.fs
  • tools.maps
• Tools — Policy & Agent Limits
  • tools.policy
  • tools (agent-level scalars)
• Channels & Integrations
  • channels
  • channels.*.<account>.tools
  • channels.*.<account>.tools.groups.<group_id>
  • channels.*.<account>.tools.groups.<group_id>.by_sender.<sender_id>
  • hooks
  • hooks.hooks[]
  • mcp
  • mcp.servers.<name>
  • mcp.servers.<name>.oauth
• Memory
  • memory
  • memory.qmd
  • memory.qmd.collections.<name>
• Scheduling & Webhooks
  • heartbeat
  • heartbeat.active_hours
  • cron
  • caldav
  • caldav.accounts.<name>
  • webhooks
  • webhooks.rate_limit
• LLM Providers
  • providers
  • providers.<name>.policy
• Voice — Text-to-Speech
  • voice.tts
  • voice.tts.elevenlabs
  • voice.tts.openai
  • voice.tts.google
  • voice.tts.piper
  • voice.tts.coqui
• Voice — Speech-to-Text
  • voice.stt
  • voice.stt.whisper
  • voice.stt.groq
  • voice.stt.deepgram
  • voice.stt.google
  • voice.stt.mistral
  • voice.stt.elevenlabs
  • voice.stt.voxtral_local
  • voice.stt.whisper_cli
  • voice.stt.sherpa_onnx
• Environment
  • env

Server & Networking

server — ServerConfig

Gateway server configuration.

auth — AuthConfig

Authentication configuration.

tls — TlsConfig

TLS configuration for the gateway HTTPS server.

graphql — GraphqlConfig

Runtime GraphQL server configuration.

ngrok — NgrokConfig

ngrok public HTTPS tunnel configuration.

tailscale — TailscaleConfig

Tailscale Serve/Funnel configuration.

upstream_proxy (top-level scalar)

failover — FailoverConfig

Automatic model/provider failover configuration.

Observability

metrics — MetricsConfig

Metrics and observability configuration.

Identity & User

identity — AgentIdentity

Agent identity (name, emoji, theme).

user — UserProfile

User profile collected during onboarding.

Chat & Agents

chat — ChatConfig

chat.compaction — CompactionConfig

agents — AgentsConfig

agents.presets.<name> — AgentPreset

agents.presets.<name>.identity (AgentIdentity)

agents.presets.<name>.sessions (SessionAccessPolicyConfig)

agents.presets.<name>.memory (PresetMemoryConfig)

modes — ModesConfig

Modes are temporary per-session prompt overlays selected with /mode. They do not create chat agents, change memory, or affect spawn_agent presets.

modes.presets.<name> — ModePreset

skills — SkillsConfig

Tools — Execution

tools.exec — ExecConfig

tools.exec.sandbox — SandboxConfig

tools.exec.sandbox.resource_limits — ResourceLimitsConfig

tools.exec.sandbox.tools_policy — ToolPolicyConfig

tools.exec.sandbox.wasm_tool_limits — WasmToolLimitsConfig

tools.exec.sandbox.wasm_tool_limits.tool_overrides. (ToolLimitOverrideConfig)

Default tool_overrides entries:

tools.browser — BrowserConfig

Tools — Web & Data

tools.web.search — WebSearchConfig

tools.web.search.perplexity — PerplexityConfig

tools.web.fetch — WebFetchConfig

tools.web.firecrawl — FirecrawlConfig

tools.fs — FsToolsConfig

tools.maps — MapsConfig

Tools — Policy & Agent Limits

tools.policy — ToolPolicyConfig

tools — Agent-level scalars

Channels & Integrations

channels — ChannelsConfig

Each channel account (channels.<channel_type>.<account_name>) is an arbitrary JSON object that may contain provider-specific keys plus a tools sub-block (see below).

channels.*.<account>.tools — ChannelToolPolicyOverride

channels.*.<account>.tools.groups.<group_id> — GroupToolPolicy

channels.*.<account>.tools.groups.<group_id>.by_sender.<sender_id> — ToolPolicyConfig

hooks — HooksConfig

hooks.hooks[] — ShellHookConfigEntry

mcp — McpConfig

mcp.servers.<name> — McpServerEntry

mcp.servers.<name>.oauth — McpOAuthOverrideEntry

Memory

memory

Struct: MemoryEmbeddingConfig

memory.qmd

Struct: QmdConfig

memory.qmd.collections.<name>

Struct: QmdCollection

Scheduling & Webhooks

heartbeat

Struct: HeartbeatConfig

heartbeat.active_hours

Struct: ActiveHoursConfig

cron

Struct: CronConfig

caldav

Struct: CalDavConfig

caldav.accounts.<name>

Struct: CalDavAccountConfig

webhooks

Struct: WebhooksConfig

webhooks.rate_limit

Struct: WebhookRateLimitConfig

LLM Providers

providers

Struct: ProvidersConfig

providers.<name> — ProviderEntry

providers.<name>.model_overrides.<model_id> — ModelOverride

models — Global Model Overrides

Struct: HashMap<String, ModelOverride>

Per-model overrides that apply across all providers. Provider-scoped overrides (providers.<name>.model_overrides.<id>) take precedence over these.

[models.claude-opus-4-6]
context_window = 1_000_000

providers.<name>.policy

Struct: ToolPolicyConfig

voice

Struct: VoiceConfig

Voice — Text-to-Speech

voice.tts

Struct: VoiceTtsConfig

voice.tts.elevenlabs

Struct: VoiceElevenLabsConfig

voice.tts.openai

Struct: VoiceOpenAiConfig

voice.tts.google

Struct: VoiceGoogleTtsConfig

voice.tts.piper

Struct: VoicePiperTtsConfig

voice.tts.coqui

Struct: VoiceCoquiTtsConfig

Voice — Speech-to-Text

voice.stt

Struct: VoiceSttConfig

voice.stt.whisper

Struct: VoiceWhisperConfig

voice.stt.groq

Struct: VoiceGroqSttConfig

voice.stt.deepgram

Struct: VoiceDeepgramConfig

voice.stt.google

Struct: VoiceGoogleSttConfig

voice.stt.mistral

Struct: VoiceMistralSttConfig

voice.stt.elevenlabs

Struct: VoiceElevenLabsSttConfig

voice.stt.voxtral_local

Struct: VoiceVoxtralLocalConfig

voice.stt.whisper_cli

Struct: VoiceWhisperCliConfig

voice.stt.sherpa_onnx

Struct: VoiceSherpaOnnxConfig

Environment

env

Struct: top-level HashMap<String, String> on MoltisConfig

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
• local/e2e-ollama — opt-in live Ollama/Qwen Playwright regression check

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 glslang-tools from the LunarG Vulkan SDK).
• local/lint uses the same clippy flags as CI and release: cargo clippy -Z unstable-options --workspace --all-features --all-targets --timings -- -D warnings (uses the nightly pinned in rust-toolchain.toml).
• 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.
• Enable the live Ollama/Qwen regression check with LOCAL_VALIDATE_OLLAMA_QWEN_E2E=1. It starts a local Ollama server on MOLTIS_E2E_OLLAMA_QWEN_API_PORT (default 11435), pulls the configured Qwen model if missing, and runs the dedicated Playwright project. Override the command with LOCAL_VALIDATE_OLLAMA_QWEN_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/start-gateway-ollama-qwen-live.sh is the opt-in live-provider harness for the custom OpenAI-compatible Qwen regression path.
• 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.

For the Qwen multiple-system-message regression path, there is also an opt-in Playwright project:

cd crates/web/ui
MOLTIS_E2E_OLLAMA_QWEN_LIVE=1 npx playwright test --project=ollama-qwen-live e2e/specs/ollama-qwen-live.spec.js

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"

Once OpenAI Codex OAuth is connected, agents can use the built-in generate_image tool to create gpt-image-2 images without an OPENAI_API_KEY. Generated images are delivered through the same channel media path as screenshots and send_image, so supported chat channels receive the image as a native attachment.

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.

Choosing a Provider

Not sure which LLM provider to use? This page compares the providers supported by Moltis so you can pick the best fit for your use case.

Quick Recommendations

Provider Comparison

Price Tier Legend

How to Choose

For personal projects or experimentation

Start with Google Gemini (generous free tier, large context) or Ollama (completely free, runs locally). Both are easy to set up and let you explore without cost pressure.

For production agent workflows

Anthropic and OpenAI are the most battle-tested for tool use and complex multi-step tasks. Anthropic’s Claude models tend to follow instructions more precisely; OpenAI offers a broader model range including reasoning models (o3, o4-mini).

For cost-sensitive workloads

DeepSeek offers the best quality-to-price ratio for most tasks. Groq and Cerebras provide extremely fast inference at low cost, though model selection is more limited.

For local / offline use

Ollama is the easiest path — install it, pull a model, and Moltis auto-detects it. Local LLM runs GGUF models directly without a separate server. Both require sufficient RAM (8GB+ for small models, 16GB+ recommended).

For access to many models

OpenRouter aggregates 100+ models behind a single API key. Useful if you want to experiment across providers without managing multiple accounts.

Setting Up a Provider

See the LLM Providers page for step-by-step setup instructions for each provider, including configuration file options and environment variables.

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}" }

[mcp.servers.remote_http]
transport = "streamable-http"
url = "https://mcp.example.com/mcp"
headers = { Authorization = "Bearer ${API_KEY}" }

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), "sse", or "streamable-http"
url = "https://mcp.example.com/mcp"  # Required when transport = "sse" or "streamable-http"
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 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 Server Secrets and Placeholders

Remote MCP servers (SSE or Streamable HTTP) 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.

Running MCP Servers in Docker

When running Moltis in Docker, you have two options for stdio-based MCP servers:

Using the built-in Node.js

The Moltis Docker image includes Node.js and npm, so most MCP servers work out of the box:

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

Tip: Mount /home/moltis/.npm as a named volume so packages are only downloaded once, and bind-mount any directories the MCP server needs to access:

docker run \
  -v moltis-npm-cache:/home/moltis/.npm \
  -v /host/path/to/data:/data \
  ...

Using Docker containers

Since the Moltis image ships the Docker CLI (docker-ce-cli), and given a Docker daemon is reachable via the mounted socket, you can also run MCP servers as isolated containers. This is useful when you need a specific Node version, want stronger isolation, or prefer official MCP Docker images:

# Run an npm-based MCP server in a container
[mcp.servers.filesystem]
command = "docker"
args = [
  "run", "--rm", "-i",
  # NOTE: bind-mount paths resolve against the HOST filesystem, not the
  # Moltis container. Use the same host path you mounted into Moltis.
  "-v", "/data:/data",
  # Cache npm downloads across container restarts
  "-v", "moltis-npx-cache:/root/.npm",
  "--entrypoint", "npx",
  "node:22-alpine",
  "-y", "@modelcontextprotocol/server-filesystem", "/data",
]

# Use an official MCP Docker image
[mcp.servers.memory]
command = "docker"
args = ["run", "--rm", "-i", "mcp/memory"]

The named volume moltis-npx-cache persists the npm cache across container restarts, avoiding re-downloads on every MCP server restart. For air-gapped environments, consider pre-building a custom image with the MCP package installed.

When using containerized MCP servers, remember to mount any directories the server needs access to with -v. Because Moltis talks to the Docker daemon via the mounted socket, bind-mount paths (-v) always reference the host filesystem — not the Moltis container’s filesystem.

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.

If you are trying to understand the difference between short-term session state, long-term memory files, and sandbox persistence, start with Memory Surfaces.

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 @tobilu/qmd or bun install -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

Session transcripts can be exported into searchable memory on /new and /reset. 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]
# Orchestration style: "hybrid", "prompt-only", "search-only", or "off"
style = "hybrid"

# Agent-authored write target policy: "hybrid", "prompt-only", "search-only", or "off"
agent_write_mode = "hybrid"

# Managed USER.md write policy: "explicit-and-auto", "explicit-only", or "off"
user_profile_write_mode = "explicit-and-auto"

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

# Embedding provider for the built-in backend: "local", "ollama", "openai", "custom", or auto-detect
# Ignored while backend = "qmd", but preserved for switching back later
# Omit this field for the real default, which is auto-detect
provider = "auto"

# 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

# Merge vector and keyword results with "rrf" or "linear"
search_merge_strategy = "rrf"

# Export sessions to memory for cross-run recall: "on-new-or-reset" or "off"
session_export = "on-new-or-reset"

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

Real defaults, if you leave the fields unset:

• style = "hybrid"
• agent_write_mode = "hybrid"
• user_profile_write_mode = "explicit-and-auto"
• backend = "builtin"
• provider = auto-detect (unset, not hardcoded local)
• disable_rag = false
• citations = "auto"
• llm_reranking = false
• search_merge_strategy = "rrf"
• session_export = "on-new-or-reset"
• [chat].prompt_memory_mode = "live-reload"

style is separate from [chat].prompt_memory_mode. Style controls whether MEMORY.md is injected and whether memory tools are exposed. Prompt memory mode controls whether prompt-visible MEMORY.md is live-reloaded or frozen per session.

The web settings page exposes both knobs in the Memory section so you can experiment without hand-editing moltis.toml.

agent_write_mode is a separate axis again. It controls where agent-authored memory writes may land:

• hybrid allows both MEMORY.md and memory/*.md
• prompt-only allows only MEMORY.md
• search-only allows only memory/*.md
• off disables agent-authored memory mutations, including memory_save, memory_forget, memory_delete, and the silent pre-compaction memory flush

user_profile_write_mode is about the managed USER.md surface, not agent memory files:

• explicit-and-auto mirrors explicit settings saves to USER.md and also allows silent browser/channel timezone or location capture
• explicit-only mirrors explicit settings saves to USER.md, but disables silent browser/channel capture
• off stops Moltis from writing USER.md; the canonical user profile remains in moltis.toml [user]

citations and search_merge_strategy are typed config enums too:

• citations = "auto" | "on" | "off"
• search_merge_strategy = "rrf" | "linear"

Interaction rules that matter in practice:

• provider, base_url, model, and api_key only apply to backend = "builtin". QMD ignores them.
• [chat].prompt_memory_mode only matters when style still allows prompt memory, hybrid or prompt-only.
• llm_reranking is only meaningful when RAG is enabled. If disable_rag = true, memory falls back to keyword search.
• session_export exports transcripts into searchable memory files. It does not inject those transcripts into the prompt directly.

Or via the web UI: Settings > Memory

Recipes

Common combinations:

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

Prompt injection from MEMORY.md is controlled separately via [chat].prompt_memory_mode. Use live-reload to reread MEMORY.md before each turn, or frozen-at-session-start to keep a stable prompt-memory snapshot for the lifetime of a session.

If sandboxing is enabled with the default workspace_mount = "ro", sandboxed commands may still read mounted memory files, but they cannot modify them directly. Durable memory mutations should use memory_save, memory_forget, or memory_delete rather than shell redirection or direct file editing inside the sandbox.

Tools

The memory system exposes five 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. This is the preferred long-term write path even when memory files are visible through a read-only sandbox mount.

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

Successful writes also return a checkpointId, so the change can be rolled back with checkpoint_restore.

Parameters:

If memory.agent_write_mode = "search-only" and file is omitted, memory_save defaults to memory/notes.md. The write mode can also reject targets that are otherwise valid paths.

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.

memory_forget

Forget saved memory using natural language. This tool searches memory, asks the configured LLM to choose which chunk or chunks match the forget request, then deletes the exact stored text through the same deterministic file mutation path used by memory_delete.

{
  "request": "Forget that I prefer dark mode",
  "dry_run": true
}

If the request is ambiguous, stale, or the exact text is not uniquely removable, memory_forget returns a preview with needs_confirmation = true instead of mutating files.

Successful mutations return checkpointIds, because forgetting multiple chunks may touch more than one file.

Parameters:

Use memory_forget for normal “forget X” requests. Use memory_delete only when you already know the exact file and exact snippet to remove.

memory_delete

Forget saved memory by removing an exact snippet from a memory file or deleting the whole file. This mutates the backing Markdown file, not just the index.

{
  "file": "MEMORY.md",
  "text": "User prefers dark mode and Vim keybindings.\n"
}

To delete an entire memory note instead:

{
  "file": "memory/obsolete-note.md",
  "delete_file": true
}

Successful deletes also return a checkpointId, so the previous file state can be restored with checkpoint_restore.

Parameters:

memory_delete uses the same path validation rules as memory_save, updates the search index immediately, and can clean up stale index entries when a file is removed. It is the low-level exact-delete primitive that powers memory_forget.

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)

This pre-compaction flush obeys memory.agent_write_mode. In off mode, the flush is skipped entirely. 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          │  │
│  │ memory_delete   │  │  (pre-compact)   │  │  Validation    │  │
│  │  (agent tools)  │  │                  │  │                │  │
│  └─────────────────┘  └──────────────────┘  └────────────────┘  │
├──────────────────────────────────────────────────────────────────┤
│                      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 @tobilu/qmd or bun install -g @tobilu/qmd
2. Verify QMD is installed: qmd --version
3. Check that the path is correct in settings
4. Ensure QMD can see its index and collections: qmd status

Memory Surfaces

Moltis has several different places where information can persist. They solve different problems, and confusing them leads to very weird debugging sessions.

Quick Table

Short-Term Memory

session_state is Moltis’s short-term memory layer. It is:

• keyed by (session_key, namespace, key)
• isolated between sessions
• available to tools and runtime features that need structured, mutable state
• not automatically injected into the prompt

This is the right place for session-scoped control data, counters, cursors, or snapshots that should not become part of long-term memory.

Long-Term Memory

Long-term memory lives in Markdown files inside the Moltis data directory.

• Main agent prompt memory: ~/.moltis/MEMORY.md
• Main agent searchable memory: ~/.moltis/memory/*.md
• Non-main agent prompt memory: ~/.moltis/agents/<agent_id>/MEMORY.md
• Non-main agent searchable memory: ~/.moltis/agents/<agent_id>/memory/*.md

USER.md is not part of agent long-term memory. It is a managed user profile surface used for things like name, timezone, and cached location. Moltis also stores the canonical user profile in moltis.toml [user], then overlays USER.md when that file exists.

For main, Moltis currently prefers agents/main/MEMORY.md if it exists and falls back to the root MEMORY.md. Non-main agents do not fall back to the root file.

Prompt Memory Loading

MEMORY.md can reach the prompt in two modes:

[memory]
style = "hybrid"

[chat]
prompt_memory_mode = "live-reload"

• hybrid injects MEMORY.md into the prompt and keeps memory_search, memory_get, memory_save, memory_forget, and memory_delete available
• prompt-only injects MEMORY.md into the prompt, but hides memory tools
• search-only skips prompt injection and relies on memory tools for recall
• off disables both prompt memory injection and memory tools
• live-reload reads MEMORY.md again before each turn
• frozen-at-session-start captures the first MEMORY.md snapshot seen by a session and reuses it for later turns in that same session

The style and the mode control different things. Style decides whether prompt memory exists at all, and whether memory tools are exposed. Mode only matters when prompt memory is enabled. Frozen snapshots are stored in session_state, so they are session-scoped rather than a process-global cache.

Defaults today:

• memory.style = "hybrid"
• memory.agent_write_mode = "hybrid"
• memory.user_profile_write_mode = "explicit-and-auto"
• memory.backend = "builtin"
• memory.session_export = "on-new-or-reset"
• chat.prompt_memory_mode = "live-reload"

memory.agent_write_mode is a third axis:

• hybrid allows agent-authored writes to both MEMORY.md and memory/*.md
• prompt-only restricts agent-authored writes to MEMORY.md
• search-only restricts agent-authored writes to memory/*.md
• off disables agent-authored memory mutations, including memory_save, memory_forget, memory_delete, and the silent pre-compaction memory flush

memory.session_export is separate again:

• on-new-or-reset exports session transcripts into memory/sessions/*.md
• off disables that export hook entirely

memory.user_profile_write_mode is a fourth axis for the managed USER.md surface:

• explicit-and-auto allows settings saves and silent timezone/location capture
• explicit-only allows settings saves, but disables silent timezone/location capture
• off stops Moltis from writing USER.md; user profile data stays in moltis.toml [user]

memory.citations and memory.search_merge_strategy are typed retrieval knobs:

• citations: auto, on, or off
• search_merge_strategy: rrf or linear

Two easy-to-miss interaction rules:

• builtin embedding knobs such as memory.provider, memory.base_url, memory.model, and memory.api_key do nothing while memory.backend = "qmd"
• memory.session_export affects searchable transcript files under memory/sessions/*.md, not prompt memory injection

The chat UI exposes the active prompt-memory mode in the toolbar and full context view. Frozen sessions can also refresh their snapshot manually without restarting the session.

Sandboxes

Sandboxes have two separate persistence surfaces:

• Workspace mount, this is how commands can read or write Moltis memory files when workspace_mount is not none
• Sandbox home, this is /home/sandbox and is controlled by tools.exec.sandbox.home_persistence

Those are not the same thing.

If a file exists only in /home/sandbox, memory_search will not index it. If a file exists in the mounted Moltis workspace, it is part of Moltis’s normal memory surface, regardless of whether the command that wrote it ran in a sandbox or not.

With the default workspace_mount = "ro", sandboxed commands may still read mounted files such as MEMORY.md, but they cannot modify them directly. Durable long-term memory mutations should still happen through Moltis memory tools such as memory_save, memory_forget, and memory_delete, not via shell redirection inside the sandbox.

Between Sandboxes

Sandbox-to-sandbox sharing depends on home_persistence:

• off: nothing in sandbox home persists
• session: sandbox home persists only for that session
• shared: sandbox home is reused across sessions/containers that share the configured home

This affects /home/sandbox, not MEMORY.md semantics. Long-term memory is still governed by the mounted Moltis workspace and agent-scoped memory files.

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 purpose-built memory_save, memory_forget, and memory_delete tools with built-in path validation (only MEMORY.md and memory/*.md are mutable) 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