Quick Start

Get MateClaw running fast.

There are three sensible ways to start, and they serve different needs:

• Desktop App if you want to use the product
• Docker if you want a fast self-hosted evaluation
• Local Development if you want to modify the code

Choose the one that matches your goal. Do not overcomplicate the first run.

---

Choose Your Start Mode

Mode	Best For	Setup Cost	Editable
Desktop App	Daily use	Lowest	No
Docker	Fast self-hosted evaluation	Low	Limited
Local Development	Building and contributing	Highest	Yes

---

What You Need Before Starting

One Model Provider

MateClaw becomes useful the moment one model provider is configured.

Recommended starting points:

• DashScope for a straightforward cloud setup
• Ollama for local model usage
• OpenAI / Anthropic / Gemini / DeepSeek / Kimi / MiniMax / Zhipu / OpenRouter if already part of your stack

You do not need every provider. You need one working provider.

Runtime Requirements

For Desktop

• no Java install required
• no Node.js required
• no Maven required

For Docker

• Docker
• Docker Compose v2+

For Local Development

• Java 17+
• Maven 3.9+
• Node.js 18+
• pnpm

---

Option 1: Desktop App

The fastest way to experience MateClaw as a product is the desktop app.

1. Download the latest build from GitHub Releases
2. Install it
3. Launch the app
4. Wait for initialization
5. Log in with:

Field	Value
Username	admin
Password	admin123

Then go to:

• Settings -> Models

Add one model provider, save, and open Chat.

---

Option 2: Docker

Use Docker when you want a quick self-hosted environment without a full dev setup.

git clone https://github.com/matevip/mateclaw.git
cd mateclaw
cp .env.example .env
docker compose up -d

Open:

• http://localhost:18080

Default login:

• admin / admin123

Then configure one model provider in the UI.

---

Option 3: Local Development

Use this path if you want to work on the codebase.

Start the Backend

git clone https://github.com/matevip/mateclaw.git
cd mateclaw/mateclaw-server
mvn spring-boot:run

Backend services:

• App: http://localhost:18088
• H2 Console: http://localhost:18088/h2-console
• Swagger UI: http://localhost:18088/swagger-ui.html

Start the Frontend

cd ../mateclaw-ui
pnpm install
pnpm dev

Frontend:

• App: http://localhost:5173

Default login:

• admin / admin123

Then configure one model provider in:

• Settings -> Models

---

First Verification Checklist

Once MateClaw is running, verify these four things:

1. You can log in
2. At least one model provider is configured
3. Chat returns a response
4. The left navigation loads pages such as Agents, Tools, MCP, and Security

If these four work, the system is alive.

---

What To Do Right After Setup

Do not stop at “it boots”.

The best next steps are:

1. Send a first message in Chat
2. Create or inspect an Agent
3. Add one skill or one MCP service
4. Upload a document into Wiki knowledge base if your use case involves knowledge work
5. Review Security if tools will be used for anything sensitive

---

Where To Go Next

• User Guide for product usage
• Introduction for product framing
• Agents for runtime concepts
• Tools for extensions and tool use