MateClaw: a Java Spring Boot agent runtime you can hand to IT

The problem MateClaw solves: agents your IT department will sign off on

Most personal agent projects assume one user, one laptop and one API key. That assumption breaks the moment a support team wants an agent reading customer tickets, or a research group wants one indexing internal PDFs. Someone has to answer who approved the action, which model saw the data, and what happens when the vendor key expires at 2am.

MateClaw is built around those questions. The README states the pitch directly: other personal AI agents are built for one person, and MateClaw is the one your IT department can actually sign off on. The concrete pieces behind that claim are multi-user workspaces, approval-gated sensitive actions, a full audit trail, Spring Boot Actuator health monitoring, and per-channel error isolation so one chat platform's outage does not take down the rest.

The audience is therefore narrower than the tagline suggests. It is for platform or backend teams already comfortable with Java, Spring Boot and a relational database, who want agent behaviour to live inside the same governance boundary as the rest of their services. A solo developer who just wants a chat window over a local model will find the machinery heavier than the task.

AgentRuntimeProvider: swapping the reasoning loop without swapping the employee

The 2.2.0 release is the one that changed the architecture. The `AgentRuntimeProvider` contract separates an employee from the engine that runs its turn. Two implementations ship. The native runtime keeps ReAct, Plan-and-Execute, persistent Goals and Team Runs inside MateClaw. The DSH runtime manages `dsh-jsonrpc-agent` as an authenticated child process and streams thinking, text, tool calls, usage, completion and cancellation back as normalized runtime events.

The division of ownership is the interesting part. According to the README, DSH owns the external agent loop, while MateClaw still owns the session, workspace, credentials, tools, approvals, messages and UI projection. That means switching runtimes does not change who the employee is, what it can touch, or what gets written to the audit log. Runtime availability and capabilities are validated before startup, and DSH can be installed, verified, connection-tested, enabled or disabled from the console.

Persistent Goals are the second half of the same story. Work that takes hours is broken into bounded, recoverable segments, and the database preserves the goal checklist, continuation state, attempts, cooldowns, leases and user input accepted while the worker is busy. After a single backend instance restarts, the supervisor reconciles the interrupted attempt, reads persisted checkpoints and artifacts, and schedules the next segment. Note the qualifier: the README describes recovery after a single backend instance restarts. Nothing in the documentation describes multi-instance coordination, so treat horizontal scaling of the worker as unverified.

Installing MateClaw with docker compose and running a first employee

The Docker path is the one the repository documents. The compose file refuses to start until the database passwords are supplied, which is deliberate: the comments state that `docker compose up` fails outright when they are missing, so default credentials never reach production.

Start by copying the environment template and editing it. At minimum set `DB_PASSWORD` and `DB_ADMIN_PASSWORD` to different strong values, and set `JWT_SECRET` and `MATECLAW_CORS_ALLOWED_ORIGINS`, both of which the template marks as strongly recommended to override.

cp .env.example .env
# edit .env: DB_PASSWORD, DB_ADMIN_PASSWORD, JWT_SECRET, MATECLAW_CORS_ALLOWED_ORIGINS
openssl rand -base64 48   # value for JWT_SECRET

Then bring the stack up. The compose file defines a `postgres:16` service named `mateclaw-postgres` alongside the application, and the `.env.example` defaults point at port 5432 with database `mateclaw`.

docker compose up -d

One warning belongs here rather than in a footnote. The compose file is explicit that this stack now runs PostgreSQL 16 and that switching the database engine is a breaking change for existing deployments. On a host that previously ran the MySQL stack, `docker compose up -d` starts a fresh, empty PostgreSQL volume named `postgres_data`. The old `mysql_data` volume is not read, and the application re-seeds default data. Existing data is not lost, but it is also not visible to the new stack.

LLM API keys are not part of this step. The environment template states that DashScope, OpenAI and similar keys are added after startup in the model management area of the admin UI. Provider ordering for failover is configured in Settings then Models, where providers are dragged into priority order and the health dashboard shows routing as requests fail over.

The MySQL to PostgreSQL switch is the sharpest edge in the repository

The compose header calls the change FRESH-INSTALL-ONLY, and that phrase is doing real work. There is no automatic MySQL to PostgreSQL migration. The documented escape hatch is to dump the old stack before pulling the change, using `mysqldump` against the `mysql` service with `DB_USERNAME`, `DB_PASSWORD` and `DB_NAME`, then load the result into PostgreSQL with a cross-engine tool such as pgloader.

The alternative is to keep MySQL. The `mysql` Spring profile remains supported, so pinning a checkout to a pre-switch tag and setting `SPRING_PROFILES_ACTIVE=mysql` keeps an existing deployment running unchanged. That is a legitimate answer for a team mid-migration, but it also means two supported database paths exist in the same repository, and the default one is the newer.

Read the ordering carefully if you are upgrading. The dump has to happen before the new stack starts, because once it does, the fresh volume is what the application sees. A team that runs `docker compose up -d` first and looks for its data afterwards has already taken the step the header warns about.

A second, quieter constraint sits in the same file. The application connects as `mateclaw`, a least-privilege role created by `docker/postgres/init/10-app-role.sh` that owns only the `mateclaw` schema and is explicitly not a superuser. The bootstrap account `mateclaw_admin` is for initialisation and operations. If your operational habits assume the app connects as an owner, they need adjusting here.

LLM Wiki, channels and the surfaces you actually deploy

The knowledge layer is called LLM Wiki. Upload a PDF, a batch of markdown or a scraped page, and the README states it digests the raw material into structured pages, builds `[[links]]` between them, and preserves traceable citations for generated content. A citation drawer lets you inspect the corresponding source chunk and verify page or answer references. The distinction the project draws is between a warehouse and a library, and the citation trail is the mechanism behind it. Whether the linking quality holds on messy real-world corpora is not something the README addresses.

Deployment surfaces are deliberately plural. The Web Console is the full admin interface, including a runtime console that shows what every employee is doing and allows force-recycle in one click. The Desktop build is an Electron app with a bundled JRE 21, so no Java install is required on the client. A Webchat Widget is embedded with a single `<script>` tag. IM channels cover DingTalk, Feishu, WeChat Work, WeChat, Telegram, Discord, QQ and Slack. A Plugin SDK exposes a Java module for third-party capability packs, with `mateclaw-plugin-api`, `mateclaw-plugin-mem0`, `mateclaw-plugin-sample` and `mateclaw-plugin-search-sample` visible in the repository layout.

Search tooling is optional and configured outside the app. The environment template offers `SERPER_API_KEY` and `TAVILY_API_KEY` as a cloud search option, notes that either or neither may be configured, and points at a SearXNG sidecar as the alternative when neither is set. `SEARXNG_SECRET` should be replaced with a 32-plus character random string for production.

Where MateClaw is the wrong tool, and what to compare it against

The heaviest cost is operational. You need Java 21 or newer, Spring Boot 3.5, PostgreSQL 16 in the default Docker path, and a `.env` file with several secrets set before the stack will even start. The compose file intentionally fails on missing passwords. That is good hygiene, and it is also friction that a single-user tool does not impose.

The second limitation is scale shape. Durable Goals recovery is described for a single backend instance restarting. Nothing in the documentation covers running several workers against the same goal store, so if your workload needs horizontal worker scaling, this is not a documented path.

The third is the upgrade surface. The database engine changed between releases, and the migration is manual. A project that changes its storage engine carries that cost forward for anyone who deployed the earlier version.

For an alternative, consider a lightweight single-user agent runner such as Ollama paired with a thin local chat client. The difference in approach is not features, it is where the boundary sits. Ollama runs models locally and exposes them over an API; the surrounding agent loop, memory and channel integrations are yours to assemble. MateClaw ships that loop, plus the governance layer, and asks you to operate a database and a JVM in return. If you have one user and no audit requirement, the lighter path wins. If you have five users and an auditor, it does not.

Licence, maintenance and what an upgrade actually costs

MateClaw is Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved. That is a permissive choice, and it means the Plugin SDK can be used for proprietary capability packs. This is a description of the licence text, not legal advice; have your own counsel review anything you ship.

The repository is not archived, and the last push was on 2026-09-08. Three releases landed in the six weeks before that: v2.0.0 on 2026-07-31, v2.1.0 on 2026-08-17 and v2.2.0 on 2026-08-29. The default branch is `dev`, which is worth noting if you clone without specifying a tag; the release tags are the stable points.

Upgrade cost concentrates in two places. Database engine changes require the manual dump-and-load path described in the compose header, and runtime changes require you to re-verify `AgentRuntimeProvider` capability checks before startup. The DSH runtime can be installed, verified and connection-tested from the console, which shortens that verification, but the check still happens before the runtime is enabled rather than after.

Two startup warnings are documented in the environment template and are worth treating as deployment gates. If `JWT_SECRET` is empty, the server falls back to a built-in default and logs a warning. If `MATECLAW_CORS_ALLOWED_ORIGINS` is empty, the server allows all origins and logs a warning. Both are acceptable on a laptop and neither is acceptable on a host with a public address.

Editorial conclusion

Adopt MateClaw if you want a self-hosted, multi-user agent platform where approvals, audit trails and per-channel isolation matter more than a five-minute setup, and you are willing to run PostgreSQL 16 and a JVM. Skip it if you want a single-user desktop assistant, or if you cannot commit to the MySQL-to-PostgreSQL migration path the compose file describes. Verify two things before you commit: that your Spring profile matches the database you actually run, and that JWT_SECRET, MATECLAW_CORS_ALLOWED_ORIGINS and the DB passwords are set rather than left at the .env.example defaults.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mateaix/mateclaw on GitHub
3. Project website
4. README
5. Releases