Security notes

Protect credentials and local data

Never commit auth.json, tokens, API keys, account ids, live auth output, or transcripts containing secrets. Review tool calls and output in sensitive repositories.
Keep settings.json and .mcp.json non-secret. Use ${VAR} environment references for sensitive MCP values and store OAuth tokens under $MC_HOME/mcp-tokens/<server>.json. MCP servers default disabled; only global settings approvals can enable them, never project settings or definitions.
MCP approval is tied to the canonical source path and server name, not a definition fingerprint. Edits at the same path and name retain approval; review definition changes before launching an approved server.
Use provider-keyed auth: Codex requires OAuth; Anthropic uses ANTHROPIC_API_KEY or the anthropic API-key record. OpenAI keys are not substitutes for either.
Prefer environment variables for short-lived tests and private auth.json for longer-lived use. On Unix, it must be owner-only (0600 or stricter); CLI writes use 0600 and reject symlinked auth files before parsing.
Provider credentials authenticate assistant transport only, never Cargo, Git, or GitHub. The magi-code updater invokes cargo install; Cargo uses its own authentication.
web reads EXA_API_KEY only from the process environment for Exa search. URL open fetches directly without credentials. Active Codex search uses existing provider-keyed OAuth only at the Codex responses endpoint; credentials never cross backends and failures never fall back.
Set MC_HOME to isolate test config/state; otherwise files live under ~/.magi-code. To inspect broad session permissions, run magi-code sessions repair-permissions --dry-run. The repair never follows links or recurses and fails closed on unsafe layouts. See Troubleshooting.

Codex refreshes OAuth before applicable use, performs network exchange outside auth locks, and rejects stale/competing refresh writes. Provider generations survive logout. See Provider authentication.

MCP names must be mcp__<server>__<tool>, at most 64 UTF-8 bytes total. Both components must be non-empty ASCII letters, digits, _, or -, without __. Server ids cannot end in _; tool names may. See MCP tools.

Understand tool boundaries

bash/shell guardrails are not OS-level isolation. Sandbox hostile repositories or untrusted prompts separately. File containment checks also do not prevent every filesystem race; see Tools and safety.

web URL open accepts only public HTTP(S): no auth, custom headers, cookies, bodies, redirects, JavaScript, or local/private destinations. Downloads are capped at 512 KiB, cached text at 40,000 bytes, and redacted output at 48 KiB. Resolved private, loopback, link-local, unspecified, and multicast IPs are rejected before network access; validated DNS addresses are pinned. URL open needs no Exa key. read rejects HTTP(S) targets.

Non-Codex web search sends research queries to Exa and validates returned source URLs. Exa controls retrieval of search extracts; its DNS and redirects are not locally pinned. Direct URL open uses the protected local transport instead. Cached open makes no network requests.

ast_grep uses embedded native parsing, not a subprocess or external CLI, so it has no child-process environment profile.

Subprocess environment boundaries

The child processes below use explicit deny-by-default environment profiles instead of inheriting all ambient variables. Every profile excludes credential-shaped ambient variables. The ambient user shell is the intentional exception.

Workload	Environment and invocation
Ambient user shell (`bash` / `shell`)	On Unix, inherits the full ambient environment and invokes `/bin/bash -lc`. On Windows, it uses PowerShell (`pwsh`, then `powershell.exe`) with `-NoProfile -NonInteractive -Command`. It has no OS-level sandbox.
Sanitized hooks	On Unix, invokes `/bin/bash --noprofile --norc -c`. On Windows, it uses PowerShell (`pwsh`, then `powershell.exe`) with `-NoProfile -NonInteractive -Command`. Both use the Shell profile: `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `TMPDIR`, `LANG`, and the exact locale list below, plus the Windows startup baseline on Windows.
LSP	`PATH` only.
MCP stdio	`PATH` plus the Windows startup baseline on Windows, then the explicit configured MCP `env` overlay.

For the Shell profile, the locale entries are exactly LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, LC_PAPER, LC_NAME, LC_ADDRESS, LC_TELEPHONE, LC_MEASUREMENT, LC_IDENTIFICATION, and LC_ALL; no other LC_* variables are included. The Windows startup baseline is exactly ComSpec, PATHEXT, SystemRoot, and WINDIR, where the profile includes it. These are environment controls, not OS-level sandboxing.

Edit this page on GitHub ↗