Repository navigation
Make Codex state storage backend configurable beyond SQLite #23168
Description
What variant of Codex are you using?
CLI
What feature would you like to see?
Please consider making Codex's persistent state/log storage backend configurable, instead of hard-coding SQLite-only runtime state.
Today Codex exposes sqlite_home, which helps relocate SQLite files, but it does not solve cases where multiple Codex instances need to share the same state across machines or cluster nodes. In those environments, ~/.codex / $CODEX_HOME is often placed on a shared filesystem, and multiple Codex processes may run concurrently on different hosts. SQLite/WAL semantics on shared filesystems can become a bottleneck or a correctness/reliability risk under concurrent writers.
A useful design would be a pluggable storage backend, for example:
[state]
backend = "sqlite" # default, current behavior
[state.sqlite]
path = "/local/scratch/$USER/codex-state"
# Optional future backend
[state.postgres]
url = "postgres://codex:...@db.example.com/codex"
pool_size = 10The goal is not necessarily to remove SQLite. SQLite should remain the default for single-machine/local-first use. The request is to allow an optional server-grade backend, such as PostgreSQL, for users running Codex across multiple nodes, shared workstations, remote dev boxes, or managed enterprise environments.
Why this helps:
- safe concurrent writers across nodes
- central state for shared/remote Codex usage
- better operational tooling: backups, retention, vacuuming, monitoring
- configurable connection pooling and durability behavior
- cleaner enterprise deployment where home directories are network-mounted
This request is related to, but broader than, several SQLite-specific reliability/performance issues:
- Multi-terminal codex CLI freezes due to SQLite lock contention with no BUSY retry #20213 — multi-terminal Codex CLI freezes due to SQLite lock contention
- state_5.sqlite and logs_1.sqlite grow unboundedly on long-running installs, causing write lock contention and app restart loop #16270 — state/log SQLite DBs growing unboundedly and causing write lock contention
logs_2.sqlite-walgrows indefinitely and remains allocated after deletion because stale/suspended Codex TUI processes keep the deleted WAL open #22444 — logs SQLite WAL growth and stale processes keeping large deleted WAL files open- state runtime: corrupt
state_5.sqlite(SQLite "file is not a database") wedges startup with no auto-recovery #21750 — state SQLite corruption/recovery behavior
Additional information
For now, the workaround is to keep sqlite_home and log_dir on node-local storage instead of a shared filesystem. That avoids many SQLite shared-FS problems, but it also means Codex state is no longer shared across machines. A configurable backend would support both local-first and cluster/enterprise deployments cleanly.
Activity
box: redirect codex sqlite via CODEX_SQLITE_HOME — drop the private-h…
yoccodog commentedon Oct 15, 2026
Another concrete use case for this: moving an interactive Codex CLI conversation from a developer's laptop into a remote development VM (we use Fly Sprites), then continuing the same conversation there.
We want to preserve the conversation ID, messages, tool calls/results, and the context needed to resume, while keeping authentication, permissions, working-directory configuration, and live processes specific to the destination host. We need sequential handoff with a single writer, not simultaneous editing of one conversation from multiple machines.
Today our wrapper implements its own import path around native session files. One real conversation was about 28 MB and used
history_mode=paginated, exposing both our transfer-size limit and our importer's lack of support for that format. Those are limitations of our wrapper, not evidence of a Codex size limit, but they illustrate the maintenance cost of building portability around internal storage formats.Alongside the PostgreSQL proposal, could the storage abstraction support user-owned object storage such as AWS S3 or Google Cloud Storage? Alternatively, a documented, versioned export/import or checkpoint API would address much of this workflow without requiring every integration to reconstruct native history itself.
The important properties for us are:
CODEX_HOMEor credentials.This overlaps with #52050 (safe cross-node resume) and #47196 (supported portable export/import). A supported storage or portability boundary in the CLI harness would be valuable even if SQLite remains the default.