Running

Start the Service

Three install paths, three ways to start — pick the one you installed.

pip install

cellium-web            # WebUI，默认 0.0.0.0:18000
cellium                # 终端 TUI，同时启动 WebUI
cellium --no-webui     # 只开 TUI

Portable build

./start-cellium.sh     # Linux / macOS
CelliumAgent.exe       # Windows，双击或命令行运行

From source

python main.py         # 源码运行 WebUI
python main.py --tui   # 源码运行 TUI

Startup flags

cellium-web and python main.py accept the same flags.

Flag	说明
`--host`	Bind address, default 0.0.0.0 (reachable on the LAN)
`--port`	Port, default 18000
`--tui`	Open the full-screen terminal UI, same as cellium --tui
`--no-webui`	Run the terminal UI only, no web server

Startup Process

When Cellium Agent starts, it goes through the following initialization steps:

Logging System - Initialize logging with configurable level and buffer
DI Container - Setup core and agent dependency injection containers
Session Manager - Initialize session management with timeout and max sessions
Components - Auto-discover and load components from the components/ directory
Hot-Plug Watcher - Start file watcher for component hot-reloading
Web Application - Create FastAPI application with all routes
Channels - Register and start enabled channel adapters

Access Points

Service	URL
Chat UI	http://localhost:18000
API Docs	http://localhost:18000/docs
Health Check	http://localhost:18000/api/health

When the port is taken

If 18000 is occupied it increments until a free port is found, and the actual port is printed in the startup log. In the worst case it falls back to a random port in 30000–40000.

Flash Mode

Flash mode skips memory injection to accelerate simple tasks. Enable it in settings:

agent:
  flash_mode: true

Config file: config/agent/agent.yaml

Component Hot-Plug

The ComponentWatcher monitors the components/ directory every 3 seconds. Adding, modifying, or removing files will trigger automatic loading/unloading without restarting the service.

Logs

Level, format and output file live in config/agent/logging.yaml; logs go to cellium.log by default and the file is hot-reloaded.