nanoMuse

🧸 nanoMuse is an open-source, self-hosted personal agent in the shape of Meta's Muse, made to work in China: one agent with a name and a face, on your phone, that does things rather than answering questions, keeps working while the app is closed, and asks before anything you could not undo. Where Muse leans on Western services with APIs, nanoMuse will also work the apps on your phone through their screens (12306, WeChat, Alipay…) as a GUI agent, so the same agent works where those APIs do not exist. Any OpenAI-compatible model. One Python package, a web app inside it, and an Android app.

nanoMuse was called OpenMuse until 0.6.0. It is not related to CopilotKit's project of that name.

Start Here

What can nanoMuse do?

nanoMuse is a personal agent you talk to from your phone. It can:

• research, write pages and documents, run shell commands and Python, send mail, read your calendar and your contacts, browse the web
• operate the apps on your phone through their screens when there is no API — look up trains in 12306, read and answer WeChat, work through Alipay — with a switch, and a stop at every send or pay button (docs/gui.md)
• stop and ask before anything hard to undo, with an approval you scope (once, this task, always) and can revoke
• work on goals over weeks while the app is closed, check in on a schedule, and start work when mail arrives, an event is near or a webhook fires
• write you a feed: short posts from what it knows about you and what you asked it to follow
• remember you in a memory you can read, edit and forget, and recall it by meaning
• follow skills in the Agent Skills format and use any MCP server
• run on any OpenAI-compatible model: DeepSeek, OpenAI, OpenRouter, Ollama, vLLM, a gateway with its own headers

💡 Why nanoMuse

• The Muse shape, in the open: chat, feed, ideas, goals and library on a phone; a plush avatar that moves while it works; one agent, not a bot framework.
• Safety is the architecture: the agent never touches a tool directly. A Sentinel decides allow / ask / deny per call, keeps secrets out of the model, tracks where private data goes, and logs everything. On Linux every command runs in its own bubblewrap sandbox.
• Your machine, your model: runs on a laptop, a home server or in Docker. Chat Completions or the Responses API, streaming, native or prompt-based tool calling, local models included.
• Small enough to read: about 18k lines of typed Python, 11k of TypeScript and 800 of Kotlin. No orchestration framework underneath. About 240 tests.

📦 Install

Python 3.11 or newer, on Linux, macOS or Windows. The phone app ships inside the package; Node is only needed to change web/. The Android app is a separate download, see Android.

uv tool install nanomuse
nanomuse version

Optional: nanomuse[browser] adds the Playwright browser tool (then playwright install chromium).

🚀 Quick Start

nanomuse config init                 # writes config/config.toml
export DEEPSEEK_API_KEY=sk-...       # the default config uses DeepSeek; see Models below
nanomuse serve --host 0.0.0.0        # prints a URL and a QR code

Scan the QR code with your phone on the same Wi-Fi, or open the URL here. The link carries the access token. Setup runs the first time: your name, the agent's name and face, the model. Then try:

1. "Compare the Sony WH-1000XM6 and Bose QuietComfort Ultra for long flights and save a short comparison to headphones.md"
2. "Check how much free disk space this machine has", which stops on an approval card
3. "Set up a goal: conversational Japanese before my Kyoto trip in December, 30 minutes a day", then open Goals

Prefer the terminal? nanomuse chat is the same agent with approvals in the console; nanomuse run "task" does one task and exits. Something off? nanomuse doctor checks the config, the model and the connectors and says what to fix.

📱 Android

Download nanomuse.apk from the latest release and open it on the phone. Android 8.0 or newer, any CPU. It is not from a store, so Android asks once to allow the install.

Then nanomuse serve --host 0.0.0.0 on your computer, tap Scan QR code in the app and point the camera at the terminal. Same Wi-Fi, a VPN such as Tailscale, or your server behind TLS all work.

What the app adds over the browser tab:

• notifications while the app is closed: approvals, questions and the last word of background work, each opening the right chat
• connect by QR code, plain http:// on the LAN
• the file picker for attachments, downloads to the phone, links in the real browser

No Android? Add the web app to the home screen instead; it installs as a PWA and gets Web Push over https://. Build the APK yourself or read how it works in docs/android.md.

☁️ Deploy

docker run -d --name nanomuse -p 8787:8787 -e DEEPSEEK_API_KEY=sk-... \
  -v nanomuse-data:/data -v "$PWD/workspace:/workspace" \
  ghcr.io/nano-muse/nanomuse:latest
docker logs nanomuse            # the URL with the access token

The image is linux/amd64 and linux/arm64; :latest-browser bundles Chromium for the browser tool. From a checkout, docker compose up -d app does the same and docker compose up -d daemon advances goals with no UI. To reach it from outside your network, put it behind Tailscale or a reverse proxy with TLS rather than opening the port. Details, including a systemd unit: docs/deployment.md.

🌐 The app

nanomuse serve runs the agent and serves the app from one process: FastAPI with a WebSocket for live events, React on the phone, built into the package.

Reminders ("remind me at six to call mum"), routines ("every weekday at 07:30, a one-line weather check") and triggers (new mail, a calendar event, a webhook) are set from the chat and listed under Upcoming. Everything the app does goes through a REST + WebSocket API, documented in docs/app.md, so another front-end can drive the same agent.

🛡️ Sentinel

Every tool call goes through Sentinel before it runs. Tools declare a risk level and can raise it for a specific call (shell on rm -rf, web_fetch on a private address). First match wins:

1. deny_tools → deny
2. [[sentinel.rules]] matching the arguments → the rule's action
3. always_allow_tools / always_ask_tools
4. Taint: private data was read this session and this call sends data outside egress_allowlist → ask
5. Risk × mode: ask asks for sensitive calls, strict also for moderate ones, auto allows what is not denied
6. A call with a warning (sudo, curl | sh, code that deletes files) asks whatever the mode

[sentinel]
mode = "ask"                              # ask | strict | auto
always_ask_tools = ["send_email", "shell"]
egress_allowlist = ["*.wikipedia.org", "github.com", "*.github.com"]

[[sentinel.rules]]
tool   = "shell"
match  = { command = "*rm -rf*" }
action = "deny"

Secrets live in an encrypted vault (nanomuse vault set EMAIL_PASSWORD, or the Connections screen) and are referenced as {{vault:EMAIL_PASSWORD}}; Sentinel fills them in right before a call and redacts them from the output, so the model never sees one. Every decision goes to audit.jsonl. What is and is not covered: docs/sentinel.md; reporting: SECURITY.md.

🧠 Models

Any OpenAI-compatible endpoint. Edit [llm] in config/config.toml, or pick a preset under Connections on the phone:

[llm]
provider = "openai"                    # Chat Completions; "openai_responses" for the Responses API
model    = "deepseek-flash"
base_url = "https://api.deepseek.com"
api_key  = "${DEEPSEEK_API_KEY}"

# OpenAI:      model = "gpt-5.6-sol"  base_url = "https://api.openai.com/v1"   api_key = "${OPENAI_API_KEY}"
# Ollama:      model = "qwen3:8b"     base_url = "http://localhost:11434/v1"   api_key = "ollama"
# OpenRouter:  model = "deepseek/deepseek-flash"  base_url = "https://openrouter.ai/api/v1"
# A gateway that needs headers:  extra_headers = { "X-End-User-Id" = "nanomuse" }
# An endpoint that ignores `tools`:  tool_mode = "prompt"

Or NANOMUSE_LLM_MODEL, NANOMUSE_LLM_BASE_URL, NANOMUSE_LLM_API_KEY, NANOMUSE_LLM_PROVIDER. Local models work: qwen3:8b on Ollama passes the provider check with native tool calling, gemma3:4b through the prompt fallback. Full reference: docs/configuration.md.

Architecture

flowchart LR
    P([Phone / browser / Android]) <-- WebSocket + REST --> S[MuseService<br/>threads, scheduler, feed]
    C([Terminal]) <--> A
    S <--> A[Agent loop]
    A <--> LLM[(any OpenAI-compatible model)]
    A --> G{{Sentinel}}
    G -- allow --> T[Tools]
    G -- ask --> P
    G --> AU[(audit.jsonl)]
    G <--> V[(vault.enc)]
    T --> F[files · shell · python]
    T --> W[web_search · web_fetch · browser]
    T --> E[email · calendar · contacts]
    T --> MCP[MCP servers]
    T <--> M[(memory.db)]
    T <--> GO[(goals.db)]

More in docs/architecture.md.

nanoMuse and Meta Muse

Docs

• Configuration: every setting, environment overrides, connectors, MCP, local models
• Sentinel: policy order, rules, taint tracking, vault, audit, the sandbox
• Operating the phone: the switch, the operator and its model, what asks first, the device protocol
• The app and its API: screens, phone access, tokens, every endpoint
• Android: install, notifications, building and signing
• CLI: chat, run, serve, daemon, goals, memory, skills, vault, audit, doctor
• Architecture: source map and extension points
• Deployment: Docker, Compose, systemd, TLS
• Troubleshooting
• A simulated phone: nanoMuse as a native app on MobileGym, notifications included, in one browser tab

Releases

Latest release: v0.7.0

v0.7.0 is the rename: OpenMuse became nanoMuse.

• Package nanomuse, command nanomuse, environment variables NANOMUSE_* (OPENMUSE_* still read), data in ~/.nanomuse (an existing ~/.openmuse is kept).
• The Android app has a new application id, so it installs next to the old one; the phone stays paired after the web app migrates its storage.
• Docker image ghcr.io/nano-muse/nanomuse.

Every version: CHANGELOG.md · GitHub releases

Recent Updates

• v0.7.0 🏷️ Renamed to nanoMuse, moved to nano-muse/nanoMuse.
• v0.6.0 🧸 The Muse look, plush avatars, feed posts, a stop button, the Android app.
• v0.5.0 📎 Attachments from the phone, recall by meaning through any /embeddings, Brave / Tavily / SearXNG search.
• v0.4.0 🧩 Skills in the SKILL.md format, triggers (mail, calendar, webhooks), contacts, a sandbox for every command.
• v0.3.0 📅 Calendar connector, memory that stays tidy with undo.
• v0.2.0 📱 Scoped approvals, the phone app shell, artifacts, connections from the phone, proactivity, push notifications, browser view, 简体中文.

Roadmap

• Voice: speak a message and see it as text before it goes, through any OpenAI-compatible /audio/transcriptions
• Evals: a small set of everyday tasks with pass rates per model, so a model choice is a measured one
• iOS: the same shell as the Android app

🤝 Contribute

Use nanoMuse for a real task, report what broke, then pick something focused.

• CONTRIBUTING.md has the development setup; CI runs ruff, pytest, the web build and the Android build.
• Open issues for problems to look into.
• A pull request for a focused fix. Another language for the app is one dictionary file in web/src/i18n/.

Related projects

• nanobot: a personal assistant framework that lives in chat apps (Telegram, Discord, Slack, WeChat). Pick it for a bot in the channels you already use; nanoMuse is one agent with Muse's product shape and safety model.
• OpenClaw: the always-on gateway approach many assistant projects follow.
• browser-use: the element-annotation idea behind the browser tool.

Disclaimer

nanoMuse is an independent community project. It is not affiliated with, endorsed by, or derived from Meta Platforms, Inc. or its Muse product. The plush avatars are the project's own; the name and the design ideas are used for comparison.

License

MIT