Skip to content

Get Started

This guide takes you from a fresh install to your first conversation with ModexBot.

Prerequisite

ModexBot must be installed first. See Installation for the Windows installer or the from-source path.

First launch

Start the bot:

  • Windows (installer): double-click the "ModexBot" desktop shortcut or Start Menu entry. The bot starts and the WebUI opens in a dedicated desktop window, with a system-tray icon for quick show/hide. Prefer a plain browser? Use the Start Menu "ModexBot (Browser)" entry instead.
  • Any platform (terminal): run modexbot start, then open http://localhost:21800/webui/ in your browser.

The desktop window shows the WebUI directly, so there is nothing else to open. From the browser, use the URL above. Either way, no model needs to be configured up front; you add one next.

Add your model API key

The bot needs at least one model provider before it can reply.

  1. Open Settings in the WebUI.
  2. Go to the Models tab.
  3. Enter your provider and API key. DeepSeek, OpenAI, and other OpenAI-compatible providers are supported.
  4. Save. You can define several providers and models here and switch between them later.

Each provider can also carry extra HTTP headers, a custom endpoint URL, and an interface format, so gateways that deviate from the plain chat-completions shape still fit.

Prefer the terminal? modexbot model (or modexbot config) runs an interactive wizard that writes the same model config.

A quick tour of the WebUI

  • Streaming chat. Agent output renders incrementally as it is generated, with reasoning blocks, Markdown, syntax-highlighted code, and mermaid diagrams inline.
  • TodoPanel. When the agent breaks work into steps, a side panel tracks the live task list so you can follow progress without prompting.
  • Per-turn model selector. Pick the provider and model in the chat composer before each message. Models are defined once and shared across pools. The pick binds to the turn itself: a turn that resumes after an approval keeps the model you chose for it instead of falling back to the pool default.
  • Pool selector. A dropdown in the sidebar picks the active pool for a new conversation. Four pools ship out of the box, read straight from the scope declaration: default, coder, review, and opencode. Each conversation is pinned to its pool.
  • Workspace tabs. Every tab in the top bar is a live workspace with its own sidebar, sessions, and chat, so several workspaces can sit open side by side. The "+" menu lists recent workspaces and a directory browser for picking a new one, and opening always appends a new tab. In IM chats, /cd switches the workspace for that conversation. A switch moves only a per-session pointer: no os.chdir, no restart.
  • Settings. Six tabs cover the configuration surface: IM (adapter credentials), Models (providers and API keys), Scope, MCP (the MCP server registry), Skills, and Prompts (the agents/*.md system prompts, each editable in place). The Scope tab is a full editor for the agent declaration. It shows the workspace tree as a topology canvas, a provenance bill that itemizes where each agent's tools, memory, and approval policy come from, and a YAML editor whose save validates the file and writes it straight back to config/scopes/bot.yml. Edits are restart-effective, but the canvas and bill refresh immediately, so you can compare what is now declared against what is still running. What the declaration compiles into is the subject of Scope & Assembly.
  • Graphs. A dedicated view for graph workflows. It lists the specs found in config/graphs/, and each spec opens in an editor with a live topology preview beside the YAML. A running instance gets its own view: the topology canvas animates each deliver as a pulse along its edge, a sidebar shows node detail and an instance summary, and an event timeline tracks the run. The bundled review_cycle spec shows the idea: a reviewer and a coder loop until the reviewer approves. The engine underneath is covered in Graph Engine.
  • Session tree. Conversations are fully isolated, with parent/child branches per session, and past sessions reload from history.
  • Attachments. Upload files in the composer; the agent can read them, and you can download results back. Uploads are safety-gated by type, content sniffing, and size: images up to 20 MB, other files up to 10 MB, within a 500 MB budget per session.
  • Light and dark themes. Toggle from the sidebar.

Your first conversation

Type a message in the composer and press send. A good first prompt:

Introduce yourself and tell me what you can do.

From there, try something that uses tools, for example asking the bot to look at a file in your workspace or run a small command. Write approval ships enabled for the main agents of the bundled default and coder pools, as declared in config/scopes/bot.yml: writes and edits inside the active workspace pass through, while anything outside it makes the agent pause and ask for your go-ahead. Approve with one click in the WebUI, or reply /approve (or /deny) in chat.

What to explore next

  • Scope & Assembly: the declaration tree behind every pool, agent, and approval policy.
  • Graph Engine: how the graph-driven ReAct engine runs, suspends, and resumes.
  • Multi-Agent: pools, agent trees, and cross-pool peer messaging.
  • Memory: the multi-tier memory system and self-learning experience loop.