minibot

简体中文 | English

minibot is a local-first AI agent runtime: a FastAPI service that runs the LLM + tools + sessions loop, with a React WebUI (and Feishu / WeChat IM) for human collaboration.

  CLI / Web / Desktop / App / Feishu / WeChat
           │  REST + WebSocket
           ▼
     ┌─────────────┐
     │   minibot   │  Agent Loop → Runner → LLM / Tools
     │   :8766     │  Sessions · Memory · Skills · MCP · Cron · Sandbox
     └─────────────┘
           │
     ~/.minibot/   (config, sessions, workspace)

minibot/              # Python package (agent, API, channels, tools)
webui/                # Vite + React SPA (build → webui/dist)
Dockerfile.minibot    # Runtime + WebUI image
docs/                 # Design and phase docs
packages/             # Optional shared client packages

cd minibot
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[feishu,weixin]"
# optional: export OPENAI_API_KEY=sk-...
minibot

• Health: http://127.0.0.1:8766/health
• Dev UI: http://127.0.0.1:8766/ui/
• Packaged WebUI (when webui/dist or MINIBOT_WEBUI_DIST is set): http://127.0.0.1:8766/

cd webui
npm install
MINIBOT_API_URL=http://127.0.0.1:8766 npm run dev

The dev server proxies /api, /webui, /auth to the runtime (default :8766).

npm run build   # → webui/dist
npm test

docker build -f Dockerfile.minibot -t minibot:local .
docker run --rm -p 8766:8766 \
  -e MINIBOT_SERVER_HOST=0.0.0.0 \
  -e MINIBOT_SERVER_OPENAI_API_KEY=sk-... \
  minibot:local

Layers: environment → ~/.minibot/config.json → in-memory state.

Model presets, MCP servers, and channel credentials live in WebUI Settings / IM channels.

When minibot is wired to the shared auth service, use:

MINIBOT_SERVER_AUTH_PROVIDER=mini_auth
MINIBOT_SERVER_MINI_AUTH_BASE_URL=https://auth.liuyidi.me
MINIBOT_SERVER_MINI_AUTH_CLIENT_ID=minibot
MINIBOT_SERVER_MINI_AUTH_SCOPE=openid profile email
MINIBOT_SERVER_MINI_AUTH_CALLBACK_PATH=/auth/mini-auth/callback
MINIBOT_SERVER_REQUIRE_AUTH=true

The flow becomes:

1. GET /auth/login?next=...
2. redirect to https://auth.liuyidi.me/oauth/authorize
3. login on mini-auth
4. callback to /auth/mini-auth/callback
5. minibot sets its session cookie and continues to next

More detail: minibot/README.md, webui/README.md, docs/.

WebUI / IM channels
  → API / WebSocket bus
  → Agent loop (context + session lock)
  → Agent runner (stream + tool calls)
  → Providers (OpenAI-compat / Anthropic / …)
  → Tools (fs, exec/sandbox, web, MCP, kb, cron)
  → Session JSONL + memory + skills

cd minibot && pytest -q
cd minibot && ruff check src/minibot
cd webui && npm test

See AGENTS.md for agent-oriented repo guidance.

See CHANGELOG.md (中文).

See repository license files for details.