# micro/mu: a single Go binary for running your own agents and services

> Mu bundles an assistant, a unified inbox, self-hosted mail and chat protocols, and a service catalogue into one Go binary. It is built for people who want to run the whole stack on one machine, and it asks for API keys and a Docker volume before it does anything interesting.

**micro/mu** — A runtime for agents and services

- Repository: https://github.com/micro/mu
- Stars: 437 · Forks: 21
- Language: Go
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/micro-mu

## What problem micro/mu is trying to solve

The README frames the project around a question it states directly: how much of the system can you run yourself. Mu's answer is a single Go binary that contains the runtime, the services, the archive, the inbox and the agent system on one host. The stated goal is not to replace models, but to replace the hosted services around them: the assistant answering the front door, the SMTP server taking inbound mail on the backend, and the protocol servers in between.

The intended user is someone who already runs a server and is tired of stitching together a mail provider, a chat bridge, a search API and an assistant. Mu's pitch is that these become subcommands of one program. The README lists Micro (the default agent), Home (a launch pad), Inbox (mail, chat, SMS, WhatsApp, notes and tasks in one view) and Protocols for self-hosting SMTP, XMPP, SFTP and SSH.

That scope is the honest selling point and the honest warning. A binary that speaks SMTP and XMPP and also runs an LLM agent has a large surface, and the README does not describe a hardening model for any of it. If you only want an assistant, you are carrying mail and file-transfer code you did not ask for.

## How the runtime, services and archive fit together

The architecture described is flat rather than layered. Services are the building blocks, and each one is exposed as a mu subcommand and as an HTTP endpoint under /api/v1/<service>/<method>. The README gives the example that mu news list and mu news_list are the same call, which means the CLI is a thin generator over a service catalogue rather than a hand-written set of commands.

Data flow runs through a local archive. Services write into it, the archive stays searchable, and it becomes contextual memory for agents. That is the mechanism behind the claim that Micro can answer from what is true now rather than only from model memory. The agent does not hold the news or the prices; it calls a service and reads the result.

Agents are defined by three things in the README's wording: a name, an instruction, and the tools they may reach. Each agent gets an address, so agent@ reaches Micro and agent+yours@ reaches your own agent from anything that can send mail. That address-based routing is the most distinctive design choice here. It means your agent's identity is an email address, not an API key in a dashboard.

The code layout matches this: service/ holds the individual services, agent/ holds the agent side, client/ holds the CLI, and inbox/ and home/ are the UI surfaces. go.mod shows go-micro.dev/v6 as the service framework, modernc.org/sqlite for storage, and libraries for SMTP, SASL, WebAuthn, SFTP and chromedp.

## Installing micro/mu and making a first real call

The README gives a one-line install and a serve command. The first account you create in the browser becomes the admin.

```bash
curl -fsSL https://raw.githubusercontent.com/micro/mu/main/install.sh | sh
mu --serve
```

After that, open http://localhost:8080. If you would rather not pipe a remote script into a shell, the README also documents Docker and a source build. The Docker path clones the repository and brings up the compose file, which builds from the included Dockerfile and maps port 8080.

```bash
git clone https://github.com/micro/mu && cd mu
docker compose up
```

The compose file mounts a named volume at /data and sets HOME=/data. The comment in that file is worth reading twice: everything Mu writes lives under $HOME/.mu, and DATA_DIR used to be set but was read by nothing, so the volume stayed empty while real data sat in the container filesystem.

Setup picks a model provider. The README lists ANTHROPIC_API_KEY, ATLASCLOUD_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY and OPENAI_BASE_URL, and notes that running Ollama locally makes this free.

```bash
mu setup        # pick an AI provider, paste a key
mu --serve
```

One step is easy to miss and changes what you are actually testing. The binary is a client and by default calls the hosted instance at https://micro.mu. Point it at your own host before you conclude anything about your install.

```bash
mu login https://your.host   # saves the address and a token
mu config get                # says which instance is in use, and why
```

With that done, a service call such as mu news list hits your server. MU_URL and --url override the saved address per shell and per command.

## The mu ask and mu agent split, and why it trips people up

Two commands with almost the same name do opposite things, and the README says so plainly. mu ask runs the agent on the instance, so it needs your token and no model key of your own. mu agent runs the agent on your machine, with your own model key, renting tools from an instance over x402 and paying per call.

```bash
mu ask "what is in my inbox?"
mu ask --agent research "anything new this week?"
```

This is a real design decision, not an accident. It lets you use someone else's model budget with mu ask, or keep the model local and pay per tool call with mu agent. The cost is conceptual: the same English word points in two directions, and the README itself flags that mu agent is "easy to reach for by mistake".

x402 is the payment path for priced endpoints. The README states that a priced endpoint answers 402 without a token, and that an x402 client pays per call with no account at all. There is a mu x402 subcommand for config and your key, and examples/x402-agent/ in the repository. If you have no interest in per-call payments, this is machinery you will read past and never touch.

## Where micro/mu is the wrong tool

The most concrete limitation is the client default. Out of the box, the binary calls https://micro.mu, so commands run on a fresh install go to the hosted instance rather than yours. The README is explicit that mu news list on the machine you just installed calls the hosted instance without mu login. Until you run that command, you are not testing your own deployment, and nothing in the output necessarily tells you so.

The second limitation is configuration. Several files are embedded in the binary, and the README says editing them means rebuilding: home/cards.json, service/news/feeds.json, service/chat/prompts.json, service/video/channels.json and service/places/locations.json. Anything else lives in /admin/config on the server. That split means customising the news feeds or chat topics is a source change and a compile, not a settings edit. The README points to docs/INSTALL.md for every setting the code reads, which is where you should look before assuming a knob exists.

The third is the surface itself. Running SMTP, XMPP, SFTP and SSH from one process on one machine concentrates risk in one place, and the README does not describe rate limiting, sandboxing or a threat model for those protocol servers. If your requirement is an assistant only, a smaller tool is a better fit. If you need a documented, versioned API contract for third-party clients, the /api/v1/<service>/<method> scheme is described but no compatibility policy is stated.

## How it compares with wiring up separate services

The obvious alternative is the conventional stack: a mail server such as one built on go-smtp, a chat bridge, a search API, and an agent framework, each deployed and upgraded on its own. That approach gives you independent failure domains and lets you swap one piece without touching the others. Mu's opposite bet is that one binary on one machine is easier to reason about, and that the archive tying services together is worth more than the isolation you give up.

A second alternative is the hosted assistant model, where the agent, the tools and the memory all live with a vendor. Mu's README is written against exactly that, asking how much of the system you can run yourself. The trade is real in both directions: hosted means no SMTP server to patch, self-hosted means your mail and your agent activity stay on hardware you control.

A third comparison is within the repository itself. mu ask and mu agent are two deployment shapes for the same agent concept, one remote and one local, and choosing between them is choosing who pays for inference. That flexibility is more than most single-purpose assistants offer, and it comes with the naming confusion described above.

## Licence, maintenance and upgrade cost

Mu is licensed under AGPL-3.0, and the repository's LICENSE file is the authoritative text. The practical consequence to think about before you build on it: if you modify Mu and let users interact with it over a network, the AGPL's source-availability condition is generally understood to apply to your modified version. This is not legal advice, and how it applies to an internal deployment or a hosted one differs; if you plan to offer Mu to others, get your own reading.

The repository is not archived. Its last push was on 2026-09-10, and releases v1.8.0, v1.7.4 and v1.7.3 landed on 2026-09-10, 2026-09-08 and 2026-09-07 respectively. That cadence over a few days suggests active work at that time, though the README does not publish a support policy or a release cadence commitment.

Upgrade cost is concentrated in the embedded files. Because cards.json, feeds.json, prompts.json, channels.json and locations.json are compiled in, a version bump can overwrite your customisations unless you track them as patches. The Docker volume is the other upgrade concern: the compose file's comment records that a previous DATA_DIR setting left the volume empty, so verify after any change that your state is still under $HOME/.mu. go.mod pins go-micro.dev/v6 to a pseudo-version dated 2026-09-10, which means the service framework moves with the repository rather than on a tagged release.

## Conclusion

Adopt micro/mu if you want one binary that owns your assistant, inbox and outbound services on a machine you control, and you are comfortable with AGPL-3.0 and a client that defaults to the hosted instance until you run mu login against your own host. Do not adopt it if you need a stable HTTP API contract for third parties, or if you cannot run a model provider yourself. Before committing, verify the ADMIN variable and the $HOME/.mu volume path in docker-compose.yml, and check docs/INSTALL.md for the settings the README says the code reads.

## FAQ

### What is micro/mu?

It is a runtime for agents and services, written in Go and shipped as a single binary. It bundles an assistant called Micro, a unified inbox, a set of services exposed as mu subcommands and HTTP endpoints, and support for self-hosting SMTP, XMPP, SFTP and SSH.

### Why does mu news list call micro.mu instead of my own server?

The binary is a client and by default calls the hosted instance at https://micro.mu. The README says to run mu login https://your.host to save your address and token, and mu config get to see which instance is in use. MU_URL and --url override it per shell and per command.

### What is the difference between mu ask and mu agent?

mu ask runs the agent on the instance, so it needs your token and no model key of your own. mu agent runs the agent on your machine with your own model key, renting tools from an instance over x402 and paying per call. The README notes that mu agent is easy to reach for by mistake.

### Which API keys does micro/mu need?

The README lists ANTHROPIC_API_KEY, ATLASCLOUD_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY or OPENAI_BASE_URL for models, BRAVE_API_KEY for web search, and YOUTUBE_API_KEY for video. It says everything else, including mail, Google sign-in and Stripe, is optional, and that running Ollama locally makes the model side free.

### Can I change the news feeds or home screen cards in micro/mu?

Yes, but those files are embedded in the binary, so the README says editing them means rebuilding. The files are home/cards.json, service/news/feeds.json, service/chat/prompts.json, service/video/channels.json and service/places/locations.json. Everything else lives in /admin/config on the server.

## Sources

- [Issues](https://github.com/micro/mu/issues)
- [License: AGPL-3.0](https://github.com/micro/mu/blob/main/LICENSE)
- [micro/mu on GitHub](https://github.com/micro/mu)
- [README](https://github.com/micro/mu/blob/main/README.md)
- [Releases](https://github.com/micro/mu/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/micro-mu