This document describes the security configuration and deployment guidelines for oh-my-claudecode (OMC).

Enable all security features with a single environment variable:

export OMC_SECURITY=strict

This enables:

• Tool path restriction (AST tools confined to project root)
• Python REPL sandbox (dangerous modules/builtins blocked)
• Remote MCP server disable (Exa, Context7 not started)
• External LLM disable (Codex, Gemini workers blocked in team mode)
• Auto-update disable (prevents unverified version installs)
• Hard max iterations for persistent modes (200 cap)

Granular overrides via .claude/omc.jsonc (project) or ~/.config/claude-omc/config.jsonc (user):

{
  "security": {
    "restrictToolPaths": true,
    "pythonSandbox": true,
    "disableRemoteMcp": true,
    "disableExternalLLM": true,
    "disableAutoUpdate": true,
    "hardMaxIterations": 200
  }
}

• Strict mode: Config file can only tighten security, never relax it. Boolean flags use || (true stays true), hardMaxIterations uses Math.min (only decreases).
• Non-strict mode: Config file overrides defaults freely.

Confines ast_grep_search and ast_grep_replace to the project root directory. Prevents reading or modifying files outside the current project.

Blocks dangerous modules and builtins in the Python REPL:

Blocked modules: os, subprocess, shutil, socket, ctypes, multiprocessing, webbrowser, http.server, xmlrpc.server, importlib, sys, io, pathlib, signal

Blocked builtins: exec, eval, compile, __import__, open, breakpoint

Note: sys, io, and pathlib are intentionally blocked despite limiting some legitimate REPL usage. This is a defense-in-depth tradeoff. The Python-level blocklist is not a security boundary on its own; OS-level process isolation is recommended for untrusted code execution.

Prevents Exa (web search) and Context7 (external documentation) MCP servers from starting. No queries are sent to external servers when enabled.

Blocks Codex (OpenAI) and Gemini (Google) CLI workers from being spawned in team mode. Only Claude workers are allowed. Enforced at the getContract() level in the team worker contract system.

Overrides silentAutoUpdate in OMC config. When enabled, isSilentAutoUpdateEnabled() always returns false regardless of user config, preventing unverified npm package installs.

Caps the number of iterations in persistent modes (ralph, autopilot, ultrawork). Default: 500 (non-strict), 200 (strict). Prevents runaway loops.

# Environment
export OMC_SECURITY=strict

// .claude/omc.jsonc
{
  "security": {
    "restrictToolPaths": true,
    "pythonSandbox": true,
    "disableRemoteMcp": true,
    "disableExternalLLM": true,
    "disableAutoUpdate": true,
    "hardMaxIterations": 200
  }
}

• Use only approved LLM APIs and AI gateways
• Use only approved MCP servers
• Do not set "permission": {"*": "allow"} in Claude Code settings; prefer "ask" mode
• Avoid hook commands (hook.command) — they execute with shell: true
• Minimize sensitive environment variables (API keys, tokens) — MCP processes inherit them
• Install OMC manually (oh-my-claudecode install), not via agent
• Pin to a verified version with "disableAutoUpdate": true
• Clone repositories only from trusted sources — .mcp.json files are auto-loaded by Claude Code

These are structural characteristics that cannot be fully resolved by configuration:

If you discover a security vulnerability, please report it via GitHub Issues with the security label.