nanomuse

nanomuse [-V|--version] [command] [options]

nanomuse is the Python runtime CLI for nanoMuse, an open-source personal agent in the style of Meta's Muse. It does work (shell, files, browser, MCP servers, skills, mail, calendar, and optionally the screen of a phone or this computer) instead of only answering questions. A separate Sentinel decides what may run and what may leave the machine. Secrets live in a credential vault and are never shown to the model. Every action is written to an audit log.The console script is `nanomuse` (`nanomuse.cli:app`, Typer). `python -m nanomuse` is the same entry. Python 3.11 or newer is required. The published package version is 0.1.40. The project is not on PyPI: install from a clone with uv (`uv pip install -e ".[dev]"`), then nanomuse config init. Optional extras include browser (Playwright), hands (this computer's screen), and channels (Feishu / DingTalk / WeCom SDKs).nanomuse serve starts a FastAPI/Uvicorn app on 127.0.0.1:8787 by default. The phone, desktop, and web clients are separate builds in the same repository (Android APK, iOS TestFlight, Linux AppImage/.deb, Docker relay). Companion binaries nanomuse-device, nanomuse-browser, and nanomuse-open are a CLI bridge the agent uses inside its sandbox; off the phone they exit 2.On Linux, [sandbox] mode = "auto" (the default) runs shell and python_execute inside bubblewrap when it is installed: only the workspace is writable, the home directory is absent, and the network is off unless the command needs it.

-V, --version

Print `nanomuse` and the package version and exit. Same as nanomuse version

Path to `config.toml`. Without this, the file is searched as `$NANOMUSE_CONFIG`, then `./config/config.toml`, then `~/.nanomuse/config.toml`

Set the Sentinel to auto mode for this process: approve every action except explicit deny rules. Used by chat, run, serve, daemon, and goals run. daemon always runs in auto mode

Print the model's reasoning during chat, run, and goals run

Interactive chat. Type a request at the `You ›` prompt. Slash commands: `/help`, `/reset`, `/memory`, `/goals`, `/audit` [n], `/tools`, `/tainted`, `/permissions`, `/revoke` key, `/forget-approvals`, `/exit`. --resume continues the newest session under `<data_dir>/sessions`

Run one task and exit

Always-on agent with the mobile-first web app (chat, goals, ideas, memory, approvals). Default bind 127.0.0.1:8787. --host / --port (-p) override. An access token is printed with a QR code unless --no-qr. --no-auth turns the token off (local development only)

Advance every active goal on a loop (Sentinel auto mode). --interval is seconds between passes (default 3600). --once runs one pass and exits

Check the install: config, writable data dir, workspace, model, connectors. Paste the output into a bug report. --no-model skips the live model call

Show recent Sentinel audit entries. -n is how many (default 20). --json prints raw JSON lines

Serve this computer's screen, hands, and configured connectors over MCP on stdio (for the desktop harness). Nothing but the protocol is written to stdout

Copy the bundled example to `config/config.toml` (override with --path). --force overwrites an existing file

Print the effective configuration as JSON with API keys masked

Print which config file would be used, or say none was found

Store a secret (prompted, or --value). Reference it as `{{vault:NAME}}` in config. vault list prints names only. vault delete name removes one

Open a browser and sign in with a ChatGPT plan (PKCE). status, usage, logout, and proxy inspect or drop the session or run a loopback OpenAI-compatible server over it. --json writes one JSON object per line on stdout

Long-term goals: list, show id, add title (--step, --category, --due, --check-in), run id (let the agent advance it), status id `active|paused|done|cancelled`, delete id

One-shot reminders and event-driven work (mail, calendar, webhooks): list, add, cancel

Long-term memory: list, add, recall, forget, tidy, changes, restore id, clear (-y skips the confirm)

ICS feeds: agenda, free, feeds, add name url (the URL is stored in the vault), remove name

Address book: search, list, add, sources, add-source, remove-source

Agent Skills (`SKILL.md` folders): list, show, add (file, folder, or https URL), new, remove, enable, disable. User skills live under `<data_dir>/skills`

Chat apps (Feishu, DingTalk, WeCom, Telegram): status, pending, approve code, deny code, login, test. When nanomuse serve is running, these go through its API so the change takes effect at once

GUI-operator traces from phone tasks. --out writes a self-contained HTML page of screens and taps

config.toml search order

`--config` / `-c`, then `$NANOMUSECONFIG`, then `./config/config.toml`, then `~/.nanomuse/config.toml`. String values may use `${VAR}` or `${VAR:-default}`. Settings changed from the app are layered from `<datadir>/app-settings.json`

Default data directory (override with NANOMUSE_DATA_DIR or `data_dir` in the config): memory, goals, vault, audit log, sessions, skills, and the generated server token

Usual per-user config. nanomuse config init writes `config/config.toml` in the current tree instead. Sections include `[llm]`, `[agent]`, `[sentinel]`, `[memory]`, `[connectors.*]`, `[skills]`, `[sandbox]`, `[browser]`, `[gui]`, `[server]`, and `[cloud]`

Any OpenAI-compatible endpoint. Defaults are DeepSeek (`deepseek-flash` at `https://api.deepseek.com`, key from DEEPSEEK_API_KEY). `provider = "chatgpt"` uses nanomuse chatgpt login and needs no key. Catalogue ids such as `bailian` fill in the endpoint

`ask` (default): sensitive actions need approval. `strict`: moderate and sensitive need approval. `auto`: approve everything except deny rules. `alwaysasktools` defaults to `send_email` and `shell`. Taint tracking blocks egress to non-allowlisted hosts after private data has been read

Placeholder in config for a secret stored with nanomuse vault set. The model never sees the value

API keys. NANOMUSE_LLM_PROVIDER, NANOMUSE_LLM_MODEL, and NANOMUSE_LLM_BASE_URL override `[llm]`. NANOMUSE_WORKSPACE, NANOMUSE_SENTINEL_MODE, NANOMUSE_SERVER_HOST, NANOMUSE_SERVER_PORT, NANOMUSE_SERVER_TOKEN, and NANOMUSE_CLOUD_BASE_URL override the matching settings. NANOMUSE_CONFIG selects the config file

Needs a model: an API key, a ChatGPT sign-in, or a local OpenAI-compatible server. Without one, commands that talk to the model warn and most work fails.--auto and daemon approve every Sentinel action except explicit deny rules. --no-auth on serve is for local development; do not use it on a shared network. The default serve bind is loopback only.The Linux AppImage/.deb is the desktop GUI, not this CLI. This command is the Python runtime (`nanomuse` on PATH after an editable install).The package is not published on PyPI or typical distro indexes. Playwright browsing needs `pip install 'nanomuse[browser]'` and `playwright install chromium`. Screen control needs the hands extra. Chat-app channels need their extras and, for Feishu, a QR login.Sensitive prompts and file contents go to the configured model provider. Conversation text may pass through a nanoMuse relay when cloud sync is on; files and screenshots stay on the device.

nanoMuse is a community project under GPL-3.0-or-later. The Python line was MIT in early tags (`pre-openminis`); the phone app is based on OpenMinis 1.13 (GPL-3.0). Version 0.1.40 ("Clear") was released in October 2026. It is not affiliated with Meta; Muse is their trademark.

claude(1), aider(1), opencode(1), codex(1), llm(1), ollama(1), chatgpt(1), python(1), uv(1), bubblewrap(1), playwright(1), uvicorn(1)

Source code · Homepage · Documentation