Configuration
Settings files
| File | Scope |
|---|---|
~/.momonga/settings.json | User settings. Everything can be set here |
<project>/.momonga/settings.json | Project settings, read only for trusted folders |
~/.momonga/projects/<hash>/settings.local.json | Local settings for one project, kept outside the repository |
<project>/.mcp.json | Project MCP servers |
Project and local settings cannot set models, credentials, mcp, mcpServers, sandboxNetwork, sandbox, sandboxUnixSockets, telemetry, projectApprovals, projectChecks, retention, network, limits, ceilings, mandates, issues, forges, operations, pricing, autoUpdates, daemon, gateway, runtime, or autoMode; those keys are discarded with a warning. Nor can they set tools.ripgrep, tui.screen, tui.mouse, or tui.copyOnSelect. They can set permissions.defaultMode only to modes other than bypassPermissions and auto. In env, only a short allowlist of names is kept. Unknown keys are ignored with a warning.
Models
A model is called by its own name: the name its server gives it. Its full name is server/own-name, for example ollama/devstral-small-2:latest. Where one name is enough, the own name alone works (--model devstral-small-2); when two servers serve a model of the same name, write the full name.
Each server or account is one entry of models.connections, with an adapter (ollama, chat-completions, open-responses, anthropic, or managed), its address, and the list of its models. Each model has an id, which is the server's own name for it, and its capabilities. The server part of the full name is the connection's provider. When you leave provider out it is derived: ollama and anthropic for those adapters, the account for a subscription plan, the program for a managed connection, and otherwise a name made from the address, such as srv-127.0.0.1-1234.
Credentials are declared by reference and never written into the file:
apiKeyEnvnames an environment variable that holds the key.apiKeySecretnames an entry in the platform secret store, which you fill withmomonga secret set <name>.- An
anthropicconnection needs exactly one of the two.chat-completionsandopen-responsesconnections accept at most one.ollamaandmanagedconnections take none.
Example:
{
"models": {
"connections": [
{
"adapter": "ollama",
"baseUrl": "http://127.0.0.1:11434",
"models": [
{ "id": "your-model-name:latest", "capabilities": { "contextWindow": 32768, "maxOutputTokens": 4096 } }
]
},
{
"adapter": "chat-completions",
"provider": "example",
"baseUrl": "https://api.example.com/v1",
"apiKeyEnv": "EXAMPLE_API_KEY",
"models": [
{ "id": "example-model", "capabilities": { "contextWindow": 128000, "maxOutputTokens": 8192 } }
]
}
],
"start": "example/example-model",
"fallback": ["ollama/your-model-name:latest"],
"billingChanges": [{ "from": "metered", "to": "local" }]
},
"permissions": {
"defaultMode": "manual",
"allow": ["Bash(npm test:*)"],
"deny": ["Bash(rm:*)"]
}
}models.start is the model a new session starts with; without it, the first model in the file is used. models.fallback is the ordered list of models tried when the model of a request cannot answer. A request falls from a metered model to a local one, or the reverse, only when models.billingChanges allows that change; otherwise a warning is shown.
The values in capabilities are what you declare for your model; set them to the real values for the model you use. momonga gateway probe <model> measures a model and records the result.
A managed connection names a server program with server: the built-in fm, or a program you declare under models.servers.
Other keys under models: roles (the model for compaction, reflection, or analysis calls), dialects, headersTimeoutMs, and idleTimeoutMs. A connection can also set billing, maxConcurrency, and admissionTimeoutMs.
You can make every one of these changes without editing the file: momonga models add, remove, start, fallback, billing, role, and set in a shell, or /model, then Model settingsā¦, in a session.
A model request can be sent twice. After a crash of the gateway or the runtime, or when a server fails before its answer starts, MomongaCode sends the same request again, and the server may run and bill it twice. A second send is recorded and marked retry_of: the usage record of its answer carries retry_of_seq and its trace span carries momonga.retry_of, both naming the first send. If a server accepts an idempotency key, set idempotencyKeyHeader on its connection to the name of the header the server reads the key from, for example "idempotencyKeyHeader": "Idempotency-Key". MomongaCode then sends the same key on a request and on every resend of it, so that such a server answers and bills it once. Without the setting no key is sent. The threat model states this risk in full.
Permission rules
A rule is Tool(specifier), or a tool name alone for every call of that tool. It can name every tool of the product, including Agent, LoadTools, activate_skill and the operations tools, and an MCP tool as mcp__<server>__<tool>; mcp__<server>__* names every tool of a server. A path specifier keeps parentheses as text, so Edit(app/(auth)/**) matches app/(auth)/page.tsx. A rule that cannot be read is reported by itself when the settings load, with its file, its key and the reason, and the other rules of the file still load.
In the example above, Bash(npm test:*) allows every command whose first words are npm test, with any options after them. A rule matches only when its words are the first words of the command, with nothing between them: git -c core.pager=<program> log does not match Bash(git log:*), but it does match Bash(git:*). A * inside a Bash rule matches any text, so Bash(curl *) matches every curl command. A command the shell parser cannot follow, such as one built at run time, is not decided by a rule: you decide it.
A Bash(...) allow rule matches the command text literally, as in Claude Code, and does not check what the options of the program do. So it also allows options that make the program run another program, such as npm test --script-shell=<program> under Bash(npm test:*), find . -exec <program> {} \; under Bash(find:*), or git -c core.pager=<program> log under Bash(git:*). Write an allow rule only for a program whose every option you accept. An allow rule beside a narrower deny rule is correct use: with Bash(git:*) allowed and Bash(git push:*) denied, every git command runs except a push. momonga policy verify shows a rule that is redundant, shadowed by another, or cannot be reached, as a note that refuses nothing.
A command allowed this way still runs inside the sandbox. It has no network unless the call asks for it. The model sets network on the Bash call, either to {"hosts": ["registry.example.org"]} for named hosts (a name or an IP address, optionally with :port) or to "open" for unrestricted access, and you are asked to approve that call, with the request and the hosts named in the approval. Only you can grant it: a hook and the auto mode classifier never do. The approval holds for that one call. Network(registry.example.org) and Network(*.example.org) in the permissions of your user settings allow, ask about or deny those hosts without a question each time; a folder's settings cannot hold them. The sandboxNetwork setting refuses every request (deny), asks for each (ask, the default), or grants them without asking (allow); --sandbox-network deny, ask or allow sets it for one session and wins over the setting, and a folder's settings cannot set it. An allow rule never covers "open". With named hosts the command reaches the network only through a proxy that MomongaCode runs for that command on this machine: the proxy carries HTTP and HTTPS, lets through only the granted hosts, closes a tunnel that does not open with the granted name, and refuses a name that resolves to a loopback, link-local, or private address unless that address is granted itself. A refused host is named in the tool result. A program that does not use the proxy variables (HTTPS_PROXY and the like), such as SSH, stays without network. A command that only reads never gets the network. File deny rules, such as Read(...) and Edit(...), are enforced by the operating system, so no program the command starts can read or write a denied path. The command can write only where the sandbox allows writes. A Bash(...) deny rule, such as Bash(rm:*) in the example, matches only the command text, so it does not stop a program that an allowed command starts through an option.
The secret locations, such as ~/.ssh, ~/.aws, ~/.netrc, the home of MomongaCode and the platform key store, stay denied to reading and writing in every mode, bypassPermissions included; the threat model lists them all.
An approval shows the whole command, or every argument of an MCP call or an operation, escaped so that no character of it can redraw the screen, and the model's own description of the call labelled as the model's claim. A changed argument or description asks again. In /config, removing a permission rule or an additional folder asks first and names the rule or the folder and the settings file it comes from.
When a trusted folder adds or changes a hook group, its mandate file, a server of its .mcp.json, or one of its agents, that item is not used until you approve it: you are asked about that item, and momonga trust lists what waits for approval.
With "sandbox": "none" none of these bounds apply, so an allow rule no longer lets a command run without approval: Bash asks before every command, and in auto mode the classifier decides.
The threat model states these and the other risks that MomongaCode accepts by design.
Other settings
The reference lists every settings key with its values and the settings files that may set it.
MomongaCode stores its data under ~/.momonga (settings, state/ databases, logs/, skills/, agents/, and per-project data).
Instruction files named AGENTS.md are read into the context.
Installer options
You set nothing.
The script downloads SHA256SUMS and SHA256SUMS.sig from the latest GitHub release of yuuichieguchi/MomongaCode, verifies the signature with ssh-keygen against the release public key, checks the SHA-256 of the executable, and only then installs it. Nothing is installed if a check fails. ssh-keygen must be available; on Windows that means the OpenSSH Client optional feature.
Both installers read a few optional environment variables, such as MOMONGA_VERSION to install one version and MOMONGA_MODIFY_PATH=0 to leave your PATH alone; the reference lists them all.
The installers change your PATH only when the install directory is missing from it (install.sh checks the PATH of the running shell, install.ps1 the user PATH):
install.shadds one marked block to a shell startup file:.zshrc(underZDOTDIRif set) for zsh, the first existing of.bashrc,.bash_profile,.profile(else.bashrc) for bash,~/.config/fish/config.fish(withfish_add_path) for fish, and~/.profilefor any other shell. Running the installer again updates that block in place and prints a message about it. When the install directory is already on the PATH of the running shell, it changes nothing and prints nothing about PATH.install.ps1appends the install directory to the user PATH.- With
MOMONGA_MODIFY_PATH=0, neither script changes anything and both print the command to run in the current shell instead.