openai / openai/codex

Document the Codex App's configuration surface and which parts are stable

Open
#41,401 2 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

app config documentation enhancement remote
Dominant language
Rust
Stars
125k
Forks
19.4k
PR merge metrics
PR metrics pending

Description

What variant of Codex are you using?

App (Codex Desktop, macOS)

What feature would you like to see?

Please document the Codex App's configuration and deployment surfaces, and state a
compatibility contract for them.

The CLI is open source and its configuration is documented. The App is not, and its
configuration surface is effectively undiscoverable: the files it reads, where they
live, their schemas, the deep links it accepts, and which of these are stable across
releases.

Why this matters - a concrete symptom

Issue #18819 asks for a configurable SSH connect timeout in Codex Desktop. As far as
I can tell that setting already exists; it simply is not documented anywhere, so
users file requests for behavior that already ships, and maintainers spend attention
on it. That is a documentation gap presenting as a feature gap, and I doubt it is the
only instance.

Use case

We are deploying Codex App to a managed developer fleet. Devices are configured by
MDM, and developers are not expected to hand-configure their tooling. To do that
responsibly we need to know:

  1. Which configuration files the App reads, where they are located, and their
    schemas, including anything intended for administrator or device-management use
    rather than end-user editing.
  2. Which deep links (codex://...) are supported, and what each does.
  3. How the App discovers and stores SSH remote connections and remote projects: what
    is read from ~/.ssh/config, what is persisted in application state, and what the
    lifecycle is when a connection or project is removed.
  4. A compatibility statement for each of the above - which are supported and stable,
    which are internal and may change without notice.

Point 4 is the one that actually matters. We can discover behavior empirically; what
we cannot do is know whether it will survive the next release. Without that, any
fleet deployment either freezes on a known-good build forever or re-validates the
entire configuration surface on every update.

What would be enough

A single "Configuring and deploying the Codex App" page covering the above, with a
clear statement of what is supported. This does not require opening the App's source
and does not commit you to new APIs - only to naming what already exists and saying
which parts you intend to keep.

Additional information

Related: #18819 (requests a setting that appears to already exist).

Happy to review a draft against a real managed deployment, or to validate
pre-release builds against a documented surface.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inventorying the Codex App configuration and deployment surfaces described in the issue, using related issue #18819 as context. Document the files, schemas, deep links, SSH and project lifecycle behavior, and a stability statement for each; done means one complete “Configuring and deploying the Codex App” page that a managed fleet can use.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos
Domain
desktop, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.