moltis

What you will run into

You want one self-hosted gateway exposing your agent across several channels (web/Telegram/WhatsApp) — moltis is exactly that: a multi-channel agent gateway. The two things people trip on: downloading the release asset from GitHub direct is unusable on mainland networks (measured 3KB/s timeout — must use the gh-proxy prefix, verified 68M/16s), and the workflow order: doctor → onboard → gateway. Plus the gateway is a resident process (port binding), so know how to stop it. When to use it:

• Exposing one agent across multiple channels from your own server;
• Onboarding providers/channels/sandboxes interactively;
• Running the gateway as a resident service (production: systemd).

When not to use it: you only need a local single-client agent — a gateway is overkill.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

Single binary (Linux x86_64): download the tarball, extract moltis to /usr/local/bin. moltis doctor runs config/security checks (TOML valid, no API key leaks; data-dir permission warns are fixable with chmod 700); moltis onboard is an interactive wizard for provider/channels/sandbox; moltis gateway (the default subcommand) starts the resident gateway server. Key concepts:

• doctor: config/security check;
• onboard: interactive configuration wizard;
• gateway: resident server (default subcommand, port binding).

Where it writes: ~/.config/moltis/ (own) + data directory (~/.local/share/moltis).

Step by step

Step 1: Install the binary (why gh-proxy: mainland direct measured 3KB/s timeout)

Why: mainland direct to GitHub release assets measured 3KB/s timeout (2026-08-28) — the gh-proxy prefix is required (verified 68M/16s). The tarball extracts moltis to /usr/local/bin. Other platforms use their assets (AppImage/dmg/exe/deb/rpm).

curl -sL -o /tmp/moltis.tar.gz 'https://gh-proxy.com/https://github.com/moltis-org/moltis/releases/download/20260830.01/moltis-20260830.01-x86_64-unknown-linux-gnu.tar.gz'
tar xzf /tmp/moltis.tar.gz -C /usr/local/bin moltis
moltis --version

Expected output: moltis 20260830.01 After install, confirm:

• --version prints 20260830.01;
• /usr/local/bin is writable (precheck: OK).

Stuck? How to recover:

• download slow/timeout → confirm the network can reach gh-proxy; alternative npm/cargo mirror builds (official paths, not tested);
• tar extraction error → re-download and confirm file integrity.

Step 2: doctor check + onboard config

Why: doctor checks all config/security items (TOML valid, no API key leaks; data-dir permission warn is fixable with chmod 700); onboard is an interactive wizard for provider/channels/sandbox (human interaction).

moltis doctor

Expected output: config/security check items (TOML valid, no API key leaks; data-dir permission warn, fixable with chmod 700)

moltis onboard

Expected output: interactive config (provider/channels/sandbox; human interaction) After install, confirm:

• doctor passes all items (or only manually-fixable warns);
• after onboard, config is in place.

Stuck? How to recover:

• doctor has FAIL items → fix as prompted (permissions/config);
• onboard exits mid-way → rerun; config is incremental.

Step 3: Start the gateway (resident)

Why: gateway is the default subcommand — starts the resident gateway (port binding, serving agents externally). Ctrl+C stops it; production suggests systemd.

moltis gateway

Expected output: gateway startup log (Ctrl+C to stop; production uses systemd) After install, confirm:

• startup log has no errors;
• the service port is reachable.

Stuck? How to recover:

• port taken → check the port setting in config (~/.config/moltis/);
• startup failed → run doctor first.

How to confirm it works

Step 1: Confirm version and config health

Why: moltis --version confirms the install; moltis doctor runs all config/security checks — all passing (or only manually-fixable warns) means the environment is ready.

moltis --version
moltis doctor

Expected output: 20260830.01; config/security check items (TOML valid, no API key leaks; data-dir permission warn, fixable with chmod 700) Stuck? How to recover:

• doctor has FAIL items → fix as prompted (permissions/config);
• version mismatch → re-download and confirm file integrity.

Step 2: Confirm the gateway can start (optional, resident service)

Why: moltis gateway starting with no errors and the service port reachable confirms the external-serving path; Ctrl+C stops it when not needed.

moltis gateway

Expected output: gateway startup log (Ctrl+C to stop; production uses systemd) Stuck? How to recover:

• port taken → check the port setting in config (~/.config/moltis/);
• startup failed → run doctor first.

Other environments

• Non-Linux x86_64: official assets exist (AppImage/dmg/exe/deb/rpm) — not verified here, same command surface.
• Background process: the gateway is resident and binds a port; production suggests systemd, development stops with Ctrl+C.
• Write surface: ~/.config/moltis/ (config) + ~/.local/share/moltis (data), both own directories, no shared registration surface — co-install judged all possible-compatible.

Daily usage

Startup and entry

• Gateway: moltis gateway (resident); production uses systemd;
• Command surface: moltis --help (gateway/acp/agent/channels/sessions/config/models/providers/onboard/doctor/auth/skills/hooks/sandbox).

Common operations

Operation 1: View the command list

moltis --help

Expected output: gateway/acp/agent/channels/sessions/config/models/providers/onboard/doctor/auth/skills/hooks/sandbox commands Operation 2: Config check (verified here, all items pass)

moltis doctor

Expected output: config/security check items (TOML valid, no API key leaks; data-dir permission warn, fixable with chmod 700) Operation 3: Config wizard (first use)

moltis onboard

Expected output: interactive config (provider/channels/sandbox; human interaction) Operation 4: Start the gateway (default subcommand, resident process + port)

moltis gateway

Expected output: gateway startup log (Ctrl+C to stop; production uses systemd)

Data and directories

• Config: ~/.config/moltis/ (auto-generated on first run);
• Data: ~/.local/share/moltis or the install share/moltis/ (memory/session/channel data).

Uninstall & cleanup

note: remove the binary + own config auto-deleted; data directory and sandbox images confirmed manually

rm -f /usr/local/bin/moltis
rm -rf ~/.config/moltis
command -v moltis >/dev/null 2>&1 && echo "残留: moltis 仍存在" || echo "moltis removed: OK"

Expected output: moltis removed: OK Manual checklist (user data, not auto-deleted):

• data directory: ~/.local/share/moltis or the install share/moltis/ (memory/session/channel data)
• Docker sandbox images: moltis-related images in docker images
• channel bots (Telegram/WhatsApp): tokens invalidate with config deletion; server-side bots can stay

Dependency warnings

• Version: [20260830.01, 20260830.01] locked (isolated upgrade verify 2026-08-31: gh-proxy download 67.5MB + --version 20260830.01; date-based rolling versions — re-verify along this path on each upgrade).
• Environment: Linux x86_64; /usr/local/bin writable; other platforms use their assets (AppImage/dmg/exe/deb/rpm).
• Network: GitHub direct 3KB/s timeout (verified), must use gh-proxy (verified 68M/16s).
• Write surface: ~/.config/moltis/ (own) + data directory (~/.local/share/moltis).
• Background process: gateway resident (port binding); production uses systemd.
• Co-install: judged all possible-compatible — moltis only writes ~/.config/moltis/ (own) + data directory, no shared registration surface.

FAQ

• Q: Download slow/won't install? A: mainland direct to GitHub release assets measured 3KB/s timeout — must use the gh-proxy prefix from the install section (verified 68M/16s); npm/cargo mirror builds are alternatives.
• Q: How to start after install? A: moltis doctor to check config → moltis onboard wizard for provider → moltis gateway to start.
• Q: What is the gateway? A: the default subcommand = resident gateway server (port binding) serving agents externally; stop with Ctrl+C or manage with systemd when not in use.
• Q: Conflicts with other plugins? A: judged all possible-compatible — moltis only writes ~/.config/moltis/ (own) + data directory, no shared registration surface.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel (usage-report template); project issues go to the author's repository.