Reference

Configuration

Use when: Server configuration
Storage: config.json and environment variables
Updated: September 4, 2026

Configuration controls the HTTP listener, upstream defaults, credential directory, dashboard authentication, proxy trust, and retention settings.

Start local

{
  "listen": "127.0.0.1:8319",
  "upstream_base": "https://chatgpt.com/backend-api/codex",
  "proxy_api_key": "your-shared-proxy-key",
  "tokens": [],
  "auth_dir": "./auths"
}

A local listener is the safe first-run default. It keeps the dashboard and client API on the same machine until you deliberately place the gateway behind an authenticated HTTPS proxy.

Important fields

Field	Purpose
`listen`	Socket address for the dashboard and API server.
`proxy_api_key`	Shared key for client API requests unless managed API keys are used.
`auth_dir`	Directory where provider credential files are stored.
`disabled_files`	Credential files that should load but start disabled.
`codex_reset_credit_app_server`	Optional explicit local Codex App Server configuration for reset-credit automation and manual redemption.
`admin_auth`	Dashboard authentication: a TOTP secret, optional separate admin API key, cookie security, and session lifetime.
`trusted_proxy`	Enable only behind a reverse proxy that sanitizes forwarded IP headers.
`history_retention_days`	How long usage history remains available for charts and summaries.

Codex reset-credit App Server

Reset-credit automation uses the documented local Codex App Server JSON-RPC account API, not upstream_base or the direct HTTP quota adapter. It is experimental and off until an administrator explicitly opts in with a trusted executable and a private managed profile for each stable account.

{
  "codex_reset_credit_app_server": {
    "experimental_opt_in": true,
    "command": "/usr/local/bin/codex",
    "profile_root": "/var/lib/io-gateway/codex-app-server-profiles",
    "profiles": [{
      "account_key": "codex:account_id:org_123",
      "profile": "org_123",
      "expected_email": "[email protected]"
    }]
  }
}

The command and profile root are absolute existing paths. Profile names are simple directory names below the root, are unique per stable account, and must already hold a private file-backed Codex-managed ChatGPT login in auth.json. Every enabled profile binding must provide expected_email, which must match App Server's account/read email. This confirms the managed profile's ChatGPT email; it does not prove the upstream stable account ID, which remains the account_key mapping. On Unix, the root and profile directories must be private (0700 or stricter) and not symlinks. IO Gateway runs only codex app-server --stdio -c cli_auth_credentials_store="file" with a scrubbed profile-specific environment; it never passes the gateway credential to the child. A profile config.toml may not set sqlite_home and may select only the file credential store. See Codex reset-credit automation for the safety model and migration behavior.

Admin auth environment overrides

ADMIN_AUTH_ENABLED=true
ADMIN_AUTH_API_KEY=your-admin-key
ADMIN_AUTH_TOTP_SECRET=BASE32_SECRET
ADMIN_AUTH_SESSION_TTL_SECONDS=43200
ADMIN_AUTH_SECURE_COOKIES=true

Security notes

Dashboard and client credentials are separate

When admin_auth.api_key or ADMIN_AUTH_API_KEY is configured, dashboard login requires it in addition to TOTP. It never falls back to proxy_api_key.

Public binding is a separate deployment decision

Do not change listen to 0.0.0.0:8319 until dashboard authentication is enabled, client keys are protected, and the proxy in front of the gateway sanitizes forwarded headers.

Use secure cookies behind HTTPS

Set ADMIN_AUTH_SECURE_COOKIES=true when the dashboard is served through HTTPS.