Document the Codex App's configuration surface and which parts are stable
Nobody has claimed this yet.
- 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:
- 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. - Which deep links (
codex://...) are supported, and what each does. - 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. - 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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