# Codex technical tutorial: configuration and automation | llmnet Apps [← Apps overview](/en/) # Codex: technical tutorial By Ivo Donker · October 28, 2026 — created with AI assistance (writer: DeepSeek V4.1 Flash; critic: Gemini 3.8 Flash) Codex: [Review](/en/codex-review)[Install & set up](/en/codex-installatie)[News](/en/codex-nieuws)[Technical tutorial](/en/codex-tutorial) As of September 2026, compiled from our own notes and news archive; text machine-generated and editorially checked. Check versions and commands in the official documentation. This tutorial picks up where installation leaves off. It covers config.toml, sandbox and approval policy, project instructions via AGENTS.md, MCP servers, profiles, your own proxy or gateway, and Codex in scripts and CI. Keys and flags have been checked against the official documentation (as of September 2026). ## config.toml: where and in what order - User: ~/.codex/config.toml. The CODEX_HOME environment variable lets you move that directory. - Project: .codex/config.toml in your repository. This file is loaded only if you trust the project. An untrusted project does not get its own configuration or hooks, so a cloned repository cannot grant itself broader permissions. A basic configuration: model = "gpt-6-sol" model_reasoning_effort = "medium" approval_policy = "on-request" sandbox_mode = "workspace-write" ## Sandbox and approval Codex has two controls that together determine what the agent may do independently. sandbox_mode, the boundary at OS level: - read-only: reading files is allowed; editing and running commands are not without approval. - workspace-write (default): reading, editing within your working directory and ordinary local commands. For internet access, Codex asks first. - danger-full-access: no limits on files and network. Intended only for disposable environments such as a container. approval_policy, when Codex asks you: - on-request: ask interactively if the agent wants to do something outside the sandbox. - never: never ask. Anything the sandbox does not allow simply fails. - A table { granular = { ... } } for fine-grained control per category, for example MCP elicitations or approval of skills. untrusted is no longer supported and on-failure is deprecated; do not use them in new configurations. The sandbox uses Seatbelt on macOS, bubblewrap on Linux and WSL 2, and the native Windows sandbox in PowerShell. In September 2026, two escapes were closed: Heapjack (a host action from read-only without an approval prompt) and Overpatch (writing outside the working directory). Use at least CLI 0.149.0. ## Project instructions with AGENTS.md Codex builds up the instructions in this order: - Global: ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md. - Project: from the repository root to your current directory. At each level, first AGENTS.override.md, otherwise AGENTS.md. - Files closer to your current directory take precedence over earlier instructions. Together, the files may be 32 KiB by default (project_doc_max_bytes); above that, Codex stops adding. If your instruction file has a different name, add the name: project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] A practical pattern for monorepos: general conventions in the root AGENTS.md, and a short AGENTS.md per package with the specific build and test commands. ## MCP servers Adding a local server from the command line: codex mcp add context7 -- npx -y @upstash/context7-mcp Or directly in config.toml: [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] startup_timeout_sec = 20 tool_timeout_sec = 60 [mcp_servers.context7.env] MY_ENV_VAR = "waarde" [mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN" By default, Codex waits 10 seconds for a server to start (startup_timeout_sec) and 60 seconds per tool call (tool_timeout_sec). Servers that first need to download something via npx often need more startup time. ## Profiles A profile lets you switch quickly between settings, for example a lean profile for small jobs and a heavy profile for reviews. Since version 0.134.0, each profile is a separate file alongside your main configuration, containing only the values that differ. The old [profiles.x] table in config.toml is no longer supported. ~/.codex/deep-review.config.toml: model = "gpt-6-astra" model_reasoning_effort = "high" sandbox_mode = "read-only" To use: codex --profile deep-review ## A proxy or your own provider Do you want all traffic to run through your own LLM proxy, for logging, cost monitoring or key management? Then put this in your user configuration: openai_base_url = "https://proxy.example.com/v1" For a separate provider, you define your own block and select it with model_provider: model_provider = "mijnproxy" [model_providers.mijnproxy] name = "Eigen LLM-proxy" base_url = "https://proxy.example.com/v1" env_key = "MIJNPROXY_API_KEY" wire_api = "responses" env_key is the name of the environment variable containing the key, not the key itself. wire_api determines the API format: "responses" for the Responses API; without that line, Codex uses the Chat Completions format. Check which format your proxy passes through, because not every gateway supports both. ## Codex in scripts and CI codex exec runs without an interface and is intended for pipelines, pre-merge checks and scheduled tasks. codex exec --sandbox workspace-write "Draai de tests en repareer wat faalt" Useful flags: - --json: all events as JSON Lines on stdout. - -o or --output-last-message : also write the final answer to a file. - --output-schema : structured output according to a JSON Schema. - --skip-git-repo-check: run outside a git repository. - --ignore-user-config: do not load your own config.toml. That makes CI runs reproducible. - codex exec resume --last: continue the previous run. An example that returns only a verdict: CODEX_API_KEY="$CODEX_KEY" codex exec --sandbox read-only \ --output-schema review-schema.json -o review.json \ "Beoordeel de wijzigingen in deze branch op beveiligingsrisico's" Be careful with keys in CI. OpenAI recommends passing CODEX_API_KEY only to the command itself, as above, and not as an environment variable for the whole job. Otherwise, code from the repository that you run in the same job can read the key. ## Common problems - Project settings are ignored: the project is not marked as trusted; .codex/config.toml and the project hooks then do not load. - Instructions are missing: your AGENTS.md files are together larger than 32 KiB; increase project_doc_max_bytes or make the files shorter. - MCP server "timed out": increase startup_timeout_sec for servers that download something on first start. - Old profile no longer works: convert [profiles.x] to a separate file ~/.codex/x.config.toml. - Sandbox fails on Linux: install bubblewrap. Documentation: [learn.chatgpt.com/docs](https://learn.chatgpt.com/docs).