Android API Keys and the local model proxy

1.0.101 · Monica CLI Installation and Releases · GitHub Release

Bind an API Key already saved in an Android MDBX vault. Monica generates a loopback address and a revocable local key. It injects the upstream secret inside the broker; the model client never needs that secret.

Run these commands in your own terminal. ENTRY_ID is the native UUID from library. Enter the master password when prompted.

monica library
monica bind work-ai --entry <ENTRY_ID> --protocol openai
monica grant model-client --connection work-ai --repo "*" --operation model-list --operation model-invoke --ttl-minutes 240 --max-calls 1000
monica proxy-config model-client --output ./model-client.json
monica serve --proxy-grant model-client --session-minutes 60

The private JSON file contains base_url and api_key. Configure a trusted model client from those fields; keep the file outside version control and prompts. OpenAI uses http://127.0.0.1:47831/v1; Anthropic uses http://127.0.0.1:47831. For Anthropic, bind a separate saved key with --protocol anthropic. One local key selects one upstream; no protocol conversion or automatic failover.

JSON and SSE are supported: OpenAI /v1/responses and /v1/chat/completions; Anthropic /v1/messages and /v1/messages/count_tokens; both support GET /v1/models. HTTPS upstreams only, no redirects. Requests: 16 MiB; responses: 64 MiB; SSE events: 1 MiB; four concurrent upstream calls; 300 seconds per request. No WebSocket, background Responses, model pagination, or dedicated file/audio/image endpoints.

Run monica serve --proxy-grant model-client --session-minutes 60 and enter the master password to explicitly approve a one-hour proxy session. Repeat --proxy-grant to select multiple model grants. Startup reports the actual expiry for each grant (ready.data.proxy_sessions in JSON). Selected proxy sessions can outlive the ordinary five-minute freshness and idle windows, but remain capped by the original Tiga absolute deadline (default Multi: two hours from unlock), the broker lifetime, and the grant expiry. Stricter entry or collection policies still apply. Ordinary reveal/MCP permissions remain unchanged. Without --proxy-grant, the original freshness checks apply; the default broker lifetime remains five minutes.

Lock, revocation, source or policy changes, and expiry stop the session. Re-run the same serve command with the master password to authorize again; a still-valid, unspent grant keeps its local key. Sessions live only in engine memory and cannot survive restart or unlock. Database format and API Key fields are unchanged, so older Android clients can continue using their existing engine. There is no unattended automatic unlock.

Grants expire separately (default 240 minutes, maximum 1440) and may have call budgets. renew rotates the local key: run proxy-config again with --force and reload the client. revoke stops that grant; lock stops the broker; unbind removes only the local binding. Editing the Android source requires bind --replace and new grants. Source payloads, native identity, labels and private notes are preserved.

Validated with temporary MDBX vaults, synthetic credentials and a local TLS upstream. Real provider, Codex and Claude Code end-to-end integration has not been verified.

Full Chinese guide

Direct mode: write the upstream Key into client settings

To bypass the Monica proxy, use direct-config manual with a manually supplied Key, or direct-config saved with a bound Android API Key. Both generate native Codex / Claude Code settings. An explicit output file is required; host client settings are never selected automatically.

monica direct-config manual --client codex --api-base https://models.example.test --model YOUR_MODEL --output ./codex-direct/config.toml
monica direct-config saved work-ai --client claude --model YOUR_CLAUDE_MODEL --output ./claude-direct/settings.json

Manual mode uses a hidden prompt, or --secrets-stdin with {"token":"..."} from a trusted executor. Saved mode uses the vault password ({"password":"..."}), stops the current broker and checks both Tiga export and reveal authorization. Export denial is respected; proxy leases never authorize this operation. Bind OpenAI for Codex and Anthropic for Claude Code.

Codex adds /v1 to a bare origin. Claude Code removes a trailing /v1 so its SDK can append the request path. Only HTTPS API bases are accepted, not full /responses or /messages endpoints. Specify the exact model ID.

Existing files require --force to merge. Unrelated settings survive, and changed files receive a private .monica-<UUID>.bak backup before replacement. Invalid or ambiguous files are refused. Repeating an unchanged configuration creates no extra backup. Files use Unix 0600 / private Windows ACLs.

Direct settings contain the plaintext upstream Key. Monica grant expiry, budgets, revocation and locking do not control direct requests. Revoke or rotate the Key upstream and update client files and backups to disable it. Android payloads remain unchanged; engine auditing and existing root-category repair may still write to the vault.