|
| 1 | +--- |
| 2 | +title: codex-project |
| 3 | +description: A reference page for the codex-project resource |
| 4 | +--- |
| 5 | + |
| 6 | +The codex-project resource manages **per-project** Codex configuration. It writes a project-scoped `AGENTS.md`, settings, and MCP servers under a specific directory — leaving global configuration untouched. Use it alongside the [`codex`](/docs/resources/codex/codex) resource, which handles installation. |
| 7 | + |
| 8 | +## Parameters |
| 9 | + |
| 10 | +- **directory**: *(string, required)* Path to the project directory. Configuration files are written relative to this path: |
| 11 | + - `<directory>/AGENTS.md` |
| 12 | + - `<directory>/.codex/config.toml` |
| 13 | + |
| 14 | +- **agentsMd**: *(string, optional)* Content for `<directory>/AGENTS.md`. Accepts inline text, an `https://` URL, or a `codify://documentId:fileId` cloud URL. Codex walks from the project root down to the current working directory and concatenates any `AGENTS.md` files it finds, using them as project-specific instructions. |
| 15 | + |
| 16 | +- **config**: *(object, optional)* Key-value pairs to merge into `<directory>/.codex/config.toml`. On apply, the declared keys are written; on destroy, only the declared keys are removed. Supports the same keys as the global config, e.g. `model`, `approval_policy`, `sandbox_mode`, `sandbox_workspace_write`. |
| 17 | + - Note: Codex ignores `model_provider`, `openai_base_url`, `notify`, `otel`, and `profiles` in project-level config files for security reasons. |
| 18 | + |
| 19 | +- **mcpServers**: *(array, optional)* MCP servers to register for this project under `[mcp_servers]` in `<directory>/.codex/config.toml`. Each entry requires a `name` and `type`, plus transport-specific fields: |
| 20 | + - **stdio**: `{ name, type: "stdio", command, args?, env?, envVars?, cwd?, startupTimeoutSec?, toolTimeoutSec? }` — local process server |
| 21 | + - **http**: `{ name, type: "http", url, bearerTokenEnvVar?, httpHeaders? }` — remote streamable-HTTP server |
| 22 | + |
| 23 | +## Example usage |
| 24 | + |
| 25 | +### Per-project AGENTS.md and sandbox policy |
| 26 | + |
| 27 | +```json title="codify.jsonc" |
| 28 | +[ |
| 29 | + { |
| 30 | + "type": "codex-project", |
| 31 | + "directory": "~/projects/my-api", |
| 32 | + "agentsMd": "# Project Instructions\n\nThis is a Node.js API. Always use async/await.\nRun `npm test` before committing.", |
| 33 | + "config": { |
| 34 | + "sandbox_mode": "workspace-write", |
| 35 | + "approval_policy": "on-request" |
| 36 | + } |
| 37 | + } |
| 38 | +] |
| 39 | +``` |
| 40 | + |
| 41 | +### Per-project AGENTS.md with an MCP server |
| 42 | + |
| 43 | +```json title="codify.jsonc" |
| 44 | +[ |
| 45 | + { |
| 46 | + "type": "codex-project", |
| 47 | + "directory": "~/projects/my-api", |
| 48 | + "agentsMd": "# Project Instructions\n\nAlways check types with `npm run typecheck` before submitting.", |
| 49 | + "mcpServers": [ |
| 50 | + { |
| 51 | + "name": "project-db", |
| 52 | + "type": "stdio", |
| 53 | + "command": "npx", |
| 54 | + "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"] |
| 55 | + } |
| 56 | + ] |
| 57 | + } |
| 58 | +] |
| 59 | +``` |
| 60 | + |
| 61 | +### Per-project AGENTS.md from a remote URL |
| 62 | + |
| 63 | +```json title="codify.jsonc" |
| 64 | +[ |
| 65 | + { |
| 66 | + "type": "codex-project", |
| 67 | + "directory": "~/projects/my-api", |
| 68 | + "agentsMd": "codify://my-document-id:my-file-id" |
| 69 | + } |
| 70 | +] |
| 71 | +``` |
| 72 | + |
| 73 | +Or from a public HTTPS URL: |
| 74 | + |
| 75 | +```json title="codify.jsonc" |
| 76 | +[ |
| 77 | + { |
| 78 | + "type": "codex-project", |
| 79 | + "directory": "~/projects/my-api", |
| 80 | + "agentsMd": "https://raw.githubusercontent.com/my-org/dotfiles/main/AGENTS.md" |
| 81 | + } |
| 82 | +] |
| 83 | +``` |
| 84 | + |
| 85 | +### Global install + per-project config together |
| 86 | + |
| 87 | +```json title="codify.jsonc" |
| 88 | +[ |
| 89 | + { |
| 90 | + "type": "codex", |
| 91 | + "config": { |
| 92 | + "model": "gpt-5.1-codex" |
| 93 | + } |
| 94 | + }, |
| 95 | + { |
| 96 | + "type": "codex-project", |
| 97 | + "directory": "~/projects/my-api", |
| 98 | + "agentsMd": "# My API\n\nNode.js + TypeScript. Run `npm test` before any commit." |
| 99 | + } |
| 100 | +] |
| 101 | +``` |
| 102 | + |
| 103 | +## Notes |
| 104 | + |
| 105 | +- The `codex` resource must be applied before `codex-project` (it declares a dependency automatically). If Codex is not installed, this resource will report as not present. |
| 106 | +- Multiple `codex-project` entries can coexist — each unique `directory` is a separate resource instance. |
| 107 | +- Destroying a `codex-project` resource removes only the per-project files (`AGENTS.md` and the `.codex/config.toml` directory). The Codex binary and global configuration are left untouched. |
| 108 | +- The `config` parameter merges only the declared top-level keys. Existing project config not in your Codify config is left untouched. |
| 109 | +- The `agentsMd` parameter manages the entire `AGENTS.md` file. On destroy, the file is removed. |
| 110 | +- MCP servers are stored under `[mcp_servers.<name>]` in `<directory>/.codex/config.toml`. Removing an MCP server from your config removes its table; other servers are untouched. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments