Skip to content

Installation

This page covers installing ModexBot, the reference bot application built on the ModexAgent framework, with its WebUI included.

Important: what v1 distributes

Version 1 distributes the ModexBot application only. The ModexAgent framework itself is not yet published as a standalone installable package (no PyPI release). If you want the framework for your own project, clone the source repository and work from src/modex_agent/ directly.

The installer is Windows-only: no macOS or Linux packaging exists. On those platforms, use the from-source path below (it works on Windows too).

The installer bundles everything: a complete Python 3.12 runtime, all dependencies, the pre-built WebUI frontend, and a Tauri desktop shell, compiled into a single Inno Setup executable. No prerequisites, and no internet connection is needed during installation.

  1. Download. Go to Releases and download ModexBot-Setup-1.0.0-dev.exe (~103 MB).
  2. Install. Double-click the downloaded .exe and follow the wizard. It installs to %LOCALAPPDATA%\Programs\ModexBot\, no admin rights needed.
  3. Launch. Double-click the "ModexBot" desktop shortcut, or find it in the Start Menu. The bot starts and the WebUI opens in a dedicated desktop window, with a system-tray icon and background health monitoring, rather than a plain browser tab. Prefer the browser? Use the Start Menu "ModexBot (Browser)" entry instead.
  4. Configure. On first launch the WebUI opens automatically. Open Settings → Models and enter your model API key (DeepSeek, OpenAI, and more are supported).

Development release

v1.0.0-dev is the first development release. It is fully usable, but APIs, configuration layout, and packaging may still change before the stable 1.0.0.

Browser-only build

The desktop window is a Tauri 2.x shell bundled by default. If you build your own installer from source, build.bat --skip-tauri produces a browser-only variant without it.

macOS / Linux / Developers: From source

There is no installer for macOS or Linux. Run from source instead (this path also works on Windows):

git clone https://github.com/moyu-er/ModexAgent.git
cd ModexAgent/examples/bot_project

# Windows
install.bat

# Linux / macOS
chmod +x install.sh && ./install.sh

The setup script auto-installs uv and Node.js if they are missing, creates the Python environment, builds the WebUI, and registers the modexbot command on your PATH. Then:

modexbot start

Open http://localhost:21800/webui/ in your browser. Mind the /webui/ path suffix: the WebUI is served under that path, not at the server root.

No model configuration is needed to start. modexbot install (run by the setup script) builds the WebUI frontend only and does not gate on model config, so the bot starts fine without a model. Set one up afterwards via the WebUI (Settings → Models) or the modexbot config wizard.

Detailed guide

For step-by-step instructions and troubleshooting, see docs/bot-local-setup.md in the source repository.

Command-line reference

After installation, modexbot is available from any terminal:

Command Action
modexbot start Start the bot
modexbot stop Stop the bot
modexbot restart Restart the bot
modexbot status Show running status (PID, port, uptime, memory)
modexbot install Build or rebuild the WebUI frontend (-f to force)
modexbot logs -f Follow live logs
modexbot config Run the model config wizard
modexbot model Multi-provider model settings wizard

A second CLI, modexctl, ships alongside modexbot: it gives external coding agents a way to exchange cross-pool messages with the running bot.

Configuration files

ModexBot splits configuration across several files. Most never need hand-editing, since the WebUI Settings tabs and the modexbot config / modexbot model wizards cover the day-to-day surface, but knowing the layout helps for troubleshooting.

File Holds Edited via
.env TIMEZONE, Langfuse/OTEL tracing settings, training-data collection flags. Template: .env.example. Hand-edit
config/model.yml Multi-provider model config: providers, API keys, default model, per-provider headers, endpoint_url, and interface_format. Gitignored; generated by the wizard or WebUI. WebUI Models tab or modexbot model
config/im.yml IM adapter credentials (QQ, Telegram). Gitignored. WebUI IM tab
config/bot_config.yml Shared infrastructure: WebUI port, safety timeouts, observability. Hand-edit or WebUI
config/scopes/bot.yml The agent and pool declaration: every pool, agent, peer link, and approval policy in one tree. See Scope & Assembly. WebUI Scope tab
config/graphs/*.yml Graph workflow specs; ships the review_cycle example. Hand-edit or the WebUI Graphs view
config/mcp/registry.json MCP server registry. Gitignored; the shipped registry.example.json contains only the no-auth playwright server. WebUI MCP tab
agents/*.md Per-agent system prompts, one Markdown file per agent. WebUI Prompts tab

Declaration-road boot

config/scopes/bot.yml is read once per workspace build, validated against rules V1-V11 in two phases, and then compiled. Any issue is fatal: the bot refuses to start. Every issue is reported at once, not just the first, so one repair round can catch them all. The full rule list lives in Scope & Assembly.

Configurable port

The WebUI port defaults to 21800 (set in config/bot_config.yml under webui.port). Override it with the MODEXBOT_PORT environment variable if you need a different port.

Uninstall

On Windows, uninstall via Add/Remove Programs. Config files that hold secrets (.env, config/model.yml, config/im.yml) are preserved, so reinstalling picks up where you left off.

Next steps