gzds-codex

GZDS local agent runtime launcher for Codex CLI.

Install

npm install -g @openai/codex@latest
npm install -g gzds-codex

Use

cd D:\your-project
$env:GZDS_API_KEY="sk-aiapi-..."
gzds-codex

Select the initial model:

gzds-codex --model gpt-5.5

Expose several models to clients that query /v1/models:

$env:GZDS_MODELS="gpt-5.5,gpt-4.1,o3"
gzds-codex --model gpt-4.1

gzds-codex starts or reuses one shared local GZDS Agent Runtime, registers the current conversation/workspace with that runtime, writes a temporary Codex configuration that points Codex at 127.0.0.1, and launches the installed codex CLI.

Each gzds-codex launch still gets its own Codex home under GZDS_CODEX_HOME\conversations\<id>, so parallel conversations do not overwrite each other's config. The HTTP runtime is shared, so closing one Codex window does not stop the runtime used by other windows. Set GZDS_CODEX_CONVERSATION_ID only when you need a stable directory name for one specific conversation.

Requirements

• Node.js 18 or newer
• Codex CLI installed on PATH: npm install -g @openai/codex@latest
• A GZDS managed API key in GZDS_API_KEY

gzds-codex intentionally does not bundle or pin the Codex CLI. Install Codex separately so users get the current Codex release.

If Codex is missing, gzds-codex prints an install guide before starting the runtime. In an interactive terminal it can also run the installer after confirmation.

Install helpers:

gzds-codex --install-codex
gzds-codex --install-codex-npmmirror

Environment

GZDS_API_KEY             Required for calls to gzds.vip
GZDS_BASE_URL            Default: https://gzds.vip
GZDS_MODEL               Default initial model: gpt-5.5
GZDS_MODELS              Comma-separated model list exposed by /v1/models
GZDS_CODEX_HOME          Root for per-conversation Codex homes
GZDS_CODEX_CONVERSATION_ID  Optional stable id for this conversation
GZDS_CODEX_SANDBOX       Optional Codex UI sandbox mode override
GZDS_AGENT_WORKSPACE     Default: current directory
GZDS_AGENT_AUTO_APPROVE  Set 1 to skip interactive tool confirmations
GZDS_CODEGRAPH_MODE      auto, npx, path, or off. Default: auto
GZDS_CODEGRAPH_COMMAND   Optional CodeGraph executable path
GZDS_CODEGRAPH_USE_NPX   Legacy alias for GZDS_CODEGRAPH_MODE=npx
GZDS_CODEX_INSTALL_REGISTRY  Optional npm registry for --install-codex

CodeGraph

The local runtime exposes one codegraph tool to the model for low-cost code navigation: status, init, sync, search, callers, callees, and impact.

By default GZDS_CODEGRAPH_MODE=auto: the runtime uses a codegraph binary on PATH when present, and falls back to npx -y @colbymchenry/codegraph@latest when it is not. Set GZDS_CODEGRAPH_MODE=off to disable these tools.

CodeGraph is used as a cheap index, not as a replacement for source truth. The agent should still read the smallest relevant source files before editing code or giving precise implementation details.

Design notes: docs/codegraph-cli-integration.md.

Initialize a project once before asking architecture or impact questions:

codegraph init -i

To force npx execution:

$env:GZDS_CODEGRAPH_MODE="npx"
gzds-codex

On Windows, gzds-codex automatically uses danger-full-access for Codex UI sandboxing when the workspace is on a non-system drive, because Codex's Windows sandbox setup can hang there before input is enabled. GZDS Agent Runtime still keeps its own workspace path checks, approvals, and audit log.

You can also override the Codex UI sandbox explicitly:

gzds-codex --gzds-codex-sandbox danger-full-access

Release

Publish the next patch release:

cd H:\AIApi\packages\gzds-codex
npm version patch
npm publish