Audit Logging

Audit Logging

Codex Free can record an append-only log of every tool call — without leaking your source, paths, credentials, or output. It's separate from diagnostic tracing and disabled unless you configure a file.

---

Diagnostics vs audit

These are two different things:

	Diagnostics (-v/-vv, RUST_LOG)	Audit (--audit)
Purpose	Debug the server	Record activity
Destination	stderr/tracing	A JSONL file you choose
Default	info	Off

Diagnostics:

• -v → codex_free=debug,rmcp=warn: tool-start events, hashed context, argument field names, duration, output accounting.
• -vv → codex_free=trace: adds a fully redacted argument-shape summary.
• RUST_LOG overrides -v/-vv for protocol-level detail: RUST_LOG=codex_free=trace,rmcp=warn codex-free …

Turning on the audit log

codex-free --work-dir /path/to/project --audit ~/.codex-free/audit/tools.jsonl

The append-only JSONL stream starts with audit_started (server version, OS process, random run ID, command-preview policy), then emits tool_start and tool_finish records. Each tool record carries:

• an RFC 3339 timestamp, a monotonic call ID, the transport-session ID;
• hashed ChatGPT conversation and project identifiers;
• the tool name, duration, status;
• the argument shape (only fields declared by the tool's schema; unknown keys/dynamic maps are counted but not named);
• returned byte/token counts, truncation status when the tool reports it;
• resident exec_command session/PID metadata.

Not written: raw conversation identifiers, project paths, scalar argument values, image data, structured output, and returned text.

Command previews (separate opt-in)

Shell commands can contain credentials, source, paths, and env values, so previews are off by default:

codex-free --work-dir /path/to/project \
  --audit ~/.codex-free/audit/tools.jsonl \
  --audit-command-preview \
  --audit-redact-env GITHUB_TOKEN

Before a preview is written, Codex Free replaces the local MCP bearer, configured MCP-server env values, the referenced OpenAI tunnel key (when readable), values named by audit.redactEnv / --audit-redact-env, common secret-bearing env vars, and common --token, API_KEY=…, and Bearer … forms — then caps the preview at commandPreviewMaxBytes. This is defense in depth, not a proof that a command contains no secret literal. Leave previews disabled when command text itself is sensitive.

Config equivalents

The audit block mirrors the flags:

Key	Default	Description
logFile	null	JSONL destination; a relative path resolves from the launch directory. Setting it enables auditing.
includeCommandPreview	false	Include bounded, redacted 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.

--audit replaces audit.logFile; --audit-command-preview only enables previews; repeated --audit-redact-env values are merged with audit.redactEnv so a CLI invocation can't accidentally remove configured redactions.

File safety

Startup fails if an enabled audit file can't be opened safely. On Unix, newly created files use mode 0600, symlink targets are rejected, and an existing file with group/other permission bits is rejected. A later append/flush error is emitted as an error-level diagnostic without changing a tool's result.

It is a log, not a boundary

This is an operational activity log, not a tamper-evident security boundary. Model-launched commands run as the same OS user and can modify any audit file they can locate.

Keep the file outside the project access root, restrict its directory permissions, and forward it to a separately protected collector when you need independent evidence.

---

See also

• Security Model — why the file needs protecting.
• CLI Reference — the --audit* flags.
• Configuration — the audit block.