Get Started

Installing Mewbo¶

Run the server, then pick a client. Setup for each client lives on its own page, and this page routes you there.

Run the server¶

One backend powers the web console, the Android client, the REST API, and every integration. Pick one path.

Docker (recommended)¶

Prebuilt images on GHCR, and the fastest path to a stack ready for production.

# 1. Create your environment file and edit the three required vars
cp .env.example .env

# 2. Pull and start
docker compose pull && docker compose up -d

Required variables in .env.

Variable	Purpose
`MEWBO_MASTER_API_TOKEN`	API authentication token
`MEWBO_VITE_API_KEY`	Frontend key (must match `MEWBO_MASTER_API_TOKEN`)
`MEWBO_HOST_UID` / `MEWBO_HOST_GID`	Host user and group IDs (run `id` to find yours)

Docker Compose covers volume mounts, project directories, the reverse proxy, and runtime config.

From source with uv¶

Install uv, which manages Python 3.10+ for you. Then sync the API extra and start the server.

uv sync --extra api
uv run mewbo-api

The API listens on 127.0.0.1:5124 by default, where the Docker stack publishes it on host port 5125 instead. Swap --extra api for --all-extras --all-groups to pull in the wiki, MCP, and Home Assistant components plus the dev tooling.

Before your first run, set a provider key and a default model in configs/app.json. See LLM Setup. Every other key has a default, listed in the Configuration Reference.

Pick your client¶

One engine, the same behaviour and tools everywhere. Only the mode of access changes.

Terminal Ships with the base install and runs the engine locally, so it needs no separate server. Web console A browser console over the REST API. Review sessions side by side and drive scheduled runs. Android Aura, the native Android client. Start and steer sessions from your phone. API The REST API behind every surface. Drive sessions from CI, cron, or your own app.

More ways to connect¶

Home Assistant: voice control across every exposed sensor and device.
Email: send a normal email and get a styled reply minutes later.
Nextcloud Talk: a chat adapter for the channels your team already uses.
MCP server: expose Mewbo to Claude Code, Codex, Cursor, or another agent fleet over MCP.

Project instructions¶

Place a CLAUDE.md, AGENTS.md, or .claude/rules/*.md at your project root and it loads at session start. Both the Claude Code and AGENTS.md conventions work unchanged. Project Configuration has the full loading strategy, including nested packages and on-demand instruction files.