Configuration

Optional providers, service keys and runtime settings. Start with the installation guide if you have not run Micro yet.

Configuration

Nothing is required to start. Each key below switches on the feature next to it, and every one of them can also be set at /admin/config in the browser once you are admin, so the environment is for the things you want fixed at deploy time.

# An AI provider — one of these, for the agent, chat and summaries
export ANTHROPIC_API_KEY="your-key"   # Claude, from console.anthropic.com
# export ATLASCLOUD_API_KEY="your-key" # Atlas Cloud (DeepSeek, Qwen), also images
# export GEMINI_API_KEY="your-key"     # Google Gemini
# export OPENROUTER_API_KEY="your-key" # OpenRouter (one key, many models)
# export OPENAI_BASE_URL="http://localhost:11434/v1"  # Ollama or any compatible endpoint
# export OPENAI_MODEL="llama3.2"                      # which model that endpoint serves

# Video
export YOUTUBE_API_KEY="your-key"  # Google Cloud Console

# Places — falls back to OpenStreetMap without it
export GOOGLE_API_KEY="your-key"   # enable Places API (New) and the Routes API

# Web search
export BRAVE_API_KEY="your-key"

# Card top-ups for credits
# export STRIPE_SECRET_KEY="sk_live_..."
# export STRIPE_WEBHOOK_SECRET="whsec_..."

Mu also reads a dotenv file at startup: $MU_ENV_FILE, then ~/.env, then ~/.mu/.env — the first that exists wins.

Every setting the code reads is listed under Configuration reference below.

Taking payments

Callers pay in credits, prepaid against an account. Set the STRIPE_* keys to let people buy them by card; without those keys your instance runs with no metering, which is usually what you want for one you run for yourself.

Personal assistant usage is paid by default on a metered instance. New signups receive no credits, and recurring free daily allowances are disabled, including legacy daily_credits overrides. Purchased balances, paid subscription credits and previously issued one-time credits are preserved.

The public home page offers a bounded chat demo and the cached shared brief. The demo makes no tool calls, caps output at 400 tokens and accepts at most 3 requests per browser, 10 per IP and 100 across the instance in 24 hours. Limits are persisted before model work and survive restarts. Failed attempts also count. Anonymous access to the full assistant remains disabled.

Operation prices are in quota.json. Provider estimates are under Admin → Traffic → Spend; product credits are not a provider spending limit.

Monthly subscriptions

Starter defaults to $⁠12/month with 1,000 monthly usage credits; Pro defaults to $⁠45/month with 4,000 monthly usage credits when STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are configured. Override STARTER_CENTS and STARTER_CREDITS, or SUBSCRIPTION_CENTS and SUBSCRIPTION_CREDITS, together for different terms; set the corresponding cents value to 0 to stop new subscriptions for that tier. Existing subscriptions retain their purchased price and allowance. Monitor provider spend as usage grows. A publishable key is not required for hosted Checkout. Account and Pricing use these same settings. Stripe creates the recurring product/price during Checkout; no manual catalogue setup is needed. Changed settings apply to new subscribers, not existing contracts.

Starter includes a daily brief, and Pro adds an optional daily plan in the same delivery and an optional evening digest. All schedules are opt-in in Agents. Brief and plan use bounded context with no tool calls and do not spend credits. Evening Digest delivers the latest shared world roundup and a paragraph linking to each fresh blog topic piece. Choose a specific topic to receive only that topic. Delivery uses no additional model calls or credits. Benefits follow the paid period even if monthly credits are exhausted or renewal is canceled. Without a paid plan, personal brief generation stops; stored schedules are preserved. Pro Evening Digest requires an active Pro period. No service surcharge is added. Operator margins must cover processing and included generation costs.

Before the first subscription, Checkout finds this site’s enabled https://<your domain>/stripe/webhook endpoint and adds the events below, preserving existing events and the signing secret. The API key needs webhook endpoint read/write access. An absent or disabled endpoint stops Checkout before payment. You can also configure these events yourself:

• checkout.session.completed and checkout.session.async_payment_succeeded
• invoice.paid, invoice.payment_failed, invoice.payment_action_required
• customer.subscription.created, customer.subscription.updated, customer.subscription.deleted

Requests retrieve canonical objects with Stripe API version 2024-06-20, so webhook delivery order and the endpoint’s event version do not change parsing. Keep invoice/payment notifications and retry rules configured in Stripe. The first implementation uses card payments and hosted Checkout. It does not configure tax collection; configure applicable tax handling before live sales.

Usage consumes daily quota, monthly allowance, signup credit, then prepaid balance. Only paid full-period invoices grant monthly credits, once per invoice. They expire at the invoice line’s period end and cannot be transferred. No automatic overage charges or top-ups. Payment failure grants no new month. Cancellation in Account stops renewal; already paid usage remains until expiry. Resume Pro restores renewal before the period ends. Payment details opens Stripe for card changes and invoices; its limited portal configuration is created automatically. Failed reservations refund the original allowance period. App, product API and authenticated service tools use the same quota gate; x402 pay-per-call remains separate.

Preserve transactions.json and subscriptions.json with backups. The former is the authoritative grant/debit ledger; the latter keeps checkout attempts and current subscription state. A checkout response lost for more than 23 hours requires operator reconciliation in Stripe before another attempt: do not erase its record and risk creating a second subscription. Refunds/disputes and manual plan changes currently require operator reconciliation; do not assume they revoke allowances automatically.

Before enabling live sales, run Stripe test-mode purchases, renewal/test-clock, failed-card recovery, cancellation, duplicate/reordered delivery, process restart and deletion checks. Confirm model/tool margins and provider-side spending limits, and verify authenticated Account/Pricing on desktop and mobile.

Configuration reference

Use /admin/config for settings in the browser, or environment variables for deployment configuration.

Core

AI provider

One of these is needed for the agent — mu setup will prompt for it. Without one, the agent, chat and AI summaries are off and everything else works.

Service keys

Each switches on one tool. Without the key that tool is unavailable; the rest still work.

Texts

An SMS number, from Twilio. Without these the sms_* tools refuse and /sms says so; nothing else is affected.

WhatsApp has one rule SMS does not, and it is Meta’s rather than ours: this instance may only message somebody in the 24 hours after they last wrote to it. Outside that window only templates approved in advance are accepted, and there are none here — so a message sent late is refused with the reason rather than handed to the provider to drop. In practice this is invisible, because replying to somebody who just wrote is what the window is for.

Senders have to be registered before they will deliver. In the US, an unregistered long code is blocked by every major carrier: either a toll-free number with toll-free verification (free, reviewed in days, two-way, the shortest path for low volume) or a 10DLC long code with a brand and campaign registered through The Campaign Registry. In the UK, use a virtual mobile number (+447…) rather than an alphanumeric sender ID — an alphanumeric sender cannot receive, which means no replies and no way for anyone to text STOP, and US carriers reject alphanumeric senders outright.

| TWILIO_WEBHOOK_URL | — | The inbound webhook address exactly as configured on the number. Only needed if the signature check is failing: it covers the URL Twilio called, which behind a proxy is not the URL this process sees, and a mismatch drops every inbound message while Twilio reports it as 11200 |

Point each number’s inbound webhook at https://<your domain>/sms/webhook. The request is verified against TWILIO_AUTH_TOKEN, so nothing else needs opening up, and MU_DOMAIN has to match what Twilio calls or the signature will not check out.

Delivery receipts need no setting at all. Every outgoing message asks Twilio to post back to https://<your domain>/sms/status as it moves — queued, sent, delivered, failed — and the address is derived from TWILIO_WEBHOOK_URL where that is set and MU_DOMAIN otherwise, because a third place to write down where this instance lives is a third place for the three to disagree. Nothing is asked for on a box with no reachable address, so a development instance does not send Twilio retrying at localhost. The receipts are what make “it was slow” answerable: sending is not delivering, twilio.Send returns when the provider accepts a message, and without a receipt the record stops there — a text that took a second and one that took a minute look identical. /sms shows the gap when there is one, and says nothing when there is not.

File storage

Uploaded files and archived images go to the local disk by default, under ~/.mu/data. On a hosted instance that is usually the wrong place: the volume is small, is not replicated, and goes when the machine does. Set these and they go to any S3-compatible bucket instead — DigitalOcean Spaces, Cloudflare R2, Backblaze B2, MinIO, S3.

S3_BUCKET and both credentials must be set. For AWS, leave S3_ENDPOINT empty; for another S3-compatible provider, set its endpoint as well. Anything less is a misconfiguration: it is logged and the instance keeps using the disk rather than failing.

Switching an instance that already holds files is safe. New writes go to the bucket, and a read that misses there falls back to the disk, so files stored before the change keep working with no migration. Copy them across at your leisure; the fallback stops mattering once you have.

Keep the bucket private. Files are served through Mu, which checks who is asking — a public bucket would let anyone holding an object URL route around that. The bucket is shared by durable services with fixed namespaces: Files uses files/ and off-box backups use backups/.

Mail

Notifications

Mail, briefings and answers can turn up on a phone with the page closed. Nothing to configure: the first time somebody turns it on, this instance mints its own signing key and keeps it.

The payload is encrypted end to end (RFC 8291): the push service — Google’s, Apple’s, Mozilla’s — forwards bytes it cannot read. It does learn that a notification went to a device, and when.

Turning it on is a button on /account, per device, and the browser asks before anything is stored. It needs HTTPS: a service worker will not register over plain HTTP, except on localhost.

The daily briefing

DNS records are in the mail guide, and Who is allowed to send you mail is the whole inbound rule.

Social

Off unless you turn it on. Everything else in Mu works with no configuration; this one does not, because pulling strangers’ posts into your instance is a decision about what you are willing to publish, and it is yours to make.

No key and no account: the firehose is public JSON over a websocket. What arrives is about three million posts a day, so almost all of the work is refusing them — English, not a reply, long enough to stand alone, pointing at something, in one of the categories the news is already sorted by, and not an advert or a repost bot. What survives is scored, cut to one per category and one per author, and then read by your model, which picks at most three. It is allowed to pick none.

It does not hold the connection open. Ninety seconds every fifteen minutes is enough to find far more than three worth publishing, and holding it open the rest of the time costs 2.6 GB a day to fill a buffer that gets thrown away. Four fifths of what does arrive is refused on the raw bytes, before it reaches a JSON parser. Budget roughly 150 MB a day and one model call every fifteen minutes.

Without a model configured the shortlist is published in score order, which works but is noticeably worse — the arithmetic cannot tell a news story from a press release, and both look identical to it.

Channels

Sign-in

Payments

Callers pay in credits. STRIPE_* is the one that matters: set those keys and people can buy credits by card. The X402_* and chain variables configure stablecoin settlement, which funds credits — the way in is still MCP with a token.

The webhook used to be at /wallet/stripe/webhook, and that path still answers so an instance upgrading does not lose a top-up between the deploy and the dashboard edit. Move it when convenient; the old one goes away once nothing is arriving there. It is named for Stripe rather than for whichever page shows a balance because a webhook URL is a contract with somebody outside this process: it is configured once, possibly by somebody who has since left, and it should not need changing because we rearranged our own routes.

Prices and limits

Prices are data, not code. They live in quota.json at the top of the repo, embedded into the binary by main.go: one entry per operation, with its cost in credits, the label the cost tables show, and the environment variable that overrides it.

Three ways to change one, in increasing order of precedence:

1. Edit quota.json and rebuild.
2. Drop a quota.json in the data directory (~/.mu/data/quota.json). It is merged entry by entry, so a file naming one operation changes that one and leaves the rest alone — no restart needed if you call the reload.
3. Set the variable named on the entry — CREDIT_COST_SEARCH=2, CREDIT_COST_IMAGE=20. This is the container-friendly one.

An override of 0 is ignored, because an unset variable and one set to "0" look the same to a container and a price silently dropping to free is the wrong way to fail. Make something free in the file.

The full operation price list is in quota.json; account billing shows usage.

Runtime

CLI

The same binary is the client. mu --serve runs an instance; mu news list, mu ask, mu agent call one — and which one is a separate question from whether this machine is running a server.

By default the CLI calls https://micro.mu, the instance this project runs. That is deliberate: the first thing anybody does with a command-line tool is run it, and “no server configured” is a worse first answer than a result. It does mean that if you have just installed your own instance and typed mu news list, you have called somebody else’s — so point it at yours:

mu login https://your.host      # saves the address and a token, for good

Everything after that goes to your instance: the tool commands, mu ask, mu agent renting tools over x402, and mu x402 call.

To check what is in force, and what decided it:

$ mu config get
url=https://your.host (/home/you/.config/mu/config.json)
token=***

The four sources, strongest first:

A token belongs to the instance that issued it, so changing the address without changing the token gets you a 401 — mu login <url> does both.

Object storage and generation policy

Operator endpoint policy

MU_OPERATOR_ENABLED=true explicitly enables endpoints declared operator-only. It defaults to disabled. Access also requires an authenticated human account with Admin set and Agent unset. Personal access tokens must carry an explicit operator permission as well as any required service scope; existing unscoped tokens do not inherit it. Calls within Mu agent runs and x402 identities are refused. This policy does not install host-management capabilities or grant OS privileges. Mu’s existing service user and sandbox permissions are unchanged.

The separately configured tools host includes X-Mu-Catalogue-Version and X-Mu-Tool-Count headers. Reconnect MCP clients to refresh discovery after a deployment; the primary host now lists Agent, Work and Inbox operations.

Flight schedules and estimates

Set AVIATIONSTACK_API_KEY in /admin/config to enable scheduled, estimated and actual flight times on /flights. Without it, the existing aircraft tracking still works. Lookups return up to 20 provider records; missing estimates are shown as unavailable. Set the flights_status price in quota.json to cover your provider plan (the shipped price is 3 credits per lookup).

Optional Google connections

Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, and register the instance’s https://<host>/oauth2/callback redirect URI in Google Cloud. Sign-in requests only identity. Calendar, Contacts, Gmail and Drive each have a separate Connect button under Account and request read-only access only after the user chooses it. Enable Calendar API, People API, Gmail API and Drive API for the connections you intend to offer. Gmail and Drive read-only scopes are restricted scopes; external production OAuth applications require Google’s applicable verification. Testing apps are limited to the test users and token lifetime set by Google.

Previously revoked grants cannot be restored; users must reconnect. The agent can search Gmail and Drive and read selected messages or text files (including text exports of Docs, Sheets and Slides). There is no background bulk import. Looked-up content used to answer a prompt is sent to the configured AI provider, and answers may be retained in the conversation. Disconnect removes the local grant and requests revocation from Google.

Shared blog digests and daily images are enabled. Set BLOG_DIGESTS=off or DAILY_IMAGES=off to disable them independently. Blog topic pieces run throughout the day (up to eight daily); a shared world roundup is published once per day, with existing posts checked across restarts. Evening Digest delivers the past 24 hours of public blog content with an optional topic filter. The daily image is generated after 06:00 in the site timezone and archived. News summaries, tagging and arrival triage remain disabled. Personal daily brief schedules and explicit requests remain available. Model failures do not retry on another provider.

Checking Codex availability

Isolated admin preview

Codex is an opt-in provider for an administrator’s direct conversations. It does not replace the site provider, change scheduled work or require a separate agent. The Account page has a Codex preview section for admins only.

The preview currently requires Linux, Bubblewrap (apt install bubblewrap on Debian/Ubuntu), permitted unprivileged user namespaces, and the native Codex 0.156.1 executable (standalone or installed through npm). CODEX_BINARY can specify its absolute path; the default is codex on PATH. For an npm installation, Mu resolves the launcher to its bundled Linux binary without running JavaScript or exposing the npm package tree to the sandbox. Install optional dependencies when using npm (npm install -g @openai/codex@0.156.1). Set the same executable path in the server environment and the setup shell.

As the OS user that runs Micro:

mu codex login
mu codex check

Login uses a separate ~/.mu/codex-auth credential store. It does not copy or modify ~/.codex, its sessions, memories, skills or personal configuration. Check verifies the actual sandbox, the pinned protocol and a real GPT-6-Astra request with a harmless test tool. It consumes a small amount of the signed-in ChatGPT allowance. Only a successful check unlocks the Account setting. A failed check leaves the preview unavailable; there is no unsandboxed fallback. Do not disable system-wide security controls to work around a failed namespace check.

After it passes, open Account → Codex preview → Enable for my conversations. Continue using the normal Micro conversation UI. Choose Use the site provider in the same section to revert. No other account is switched. Revoking admin access also disables the preview at dispatch time. The general AI_PROVIDER setting remains unchanged; Codex is not offered as a site-wide provider yet.

Each request launches a fresh Bubblewrap filesystem/process sandbox and an ephemeral Codex thread. It mounts system runtime libraries, CA/DNS files, the Codex executable and a temporary state directory—not Micro’s data, personal home directories, host sockets or personal Codex state. Only the separate login credential is copied into temporary state; refreshes are serialized and written back, and the temporary session is removed when the request ends. Codex memories, personal apps/connectors, plugins, native shell/browser/computer tools and environment access are disabled. Micro supplies history and handles only the advertised account-scoped service tools through its existing authorization chain.

Networking remains available for OpenAI; Bubblewrap here is a filesystem and process boundary, not an outbound-network firewall. The authentication remains tied to the chosen ChatGPT account and its allowance. This preview is not a claim that a ChatGPT login is interchangeable with an API credential. A separate OpenAI account provides additional separation of account-level authority.

No Codex process, model call or readiness check runs during server startup or page rendering. The pilot serializes requests sharing its credential to avoid refresh-token races. Upgrading Codex requires revalidating the integration and running the check again; an unexpected binary version is refused on each request.

Existing personal CLI login

On the machine and OS account that will run Micro, install the Codex CLI and sign in with codex login. Then run mu codex status. This starts a temporary local App Server over stdio, checks the authentication type and lists models available to that account. It does not run a prompt or change Micro’s provider. Use the returned model identifiers; a model name shown in ChatGPT does not by itself establish availability through Codex.

This generic status probe does not validate the isolated preview. Use the setup and check above before enabling it. Do not expose an unauthenticated App Server socket or give a hosted user’s agent access to the server shell. See the App Server protocol and authentication guide.