Codex

Assign an issue to Codex and work it in your local repository.

Enable Codex

A workspace owner or administrator can enable Codex under Settings → Integrations → Codex. Assign an issue to Codex or mention @codex in an issue comment to queue a run. Members can dispatch work; guests cannot. Assignment and mention dispatch have separate switches.

Start a worker

Use Node 18.20 or newer. Install Codex and sign in with codex login, or privately set your own CODEX_API_KEY. Velocity uses your Codex account and does not meter these runs as Velocity AI operations.

npm install --global https://github.com/velocity-quest/velocity-agent/releases/download/agent-v0.5.2/velocity-agent-0.5.2.tgz
velocity-agent login
velocity-agent whoami
velocity-agent status --agent codex --team YOUR_TEAM
velocity-agent run --agent codex --repo /path/to/repository --team YOUR_TEAM

Select one or more workspaces during Velocity login. The worker processes all approved workspaces by default; add --workspace <id-or-slug> to focus on one. Sign in again to expand an older grant. For SSH or a browser on another machine, use velocity-agent login --no-browser and paste the code shown by Velocity. Saved credentials are private and refresh automatically; velocity-agent logout revokes the saved grant. Workspace connection tokens also work through VELOCITY_MCP_TOKEN; see the MCP setup guide.

Repository and delivery

The worker only takes Codex issue runs from the specified team and authenticated workspace. Start from a clean, writable Git checkout with an initial commit and configured Git author. Existing changes are preserved; commit or stash them before starting the worker. Each attempt creates a new branch, lets Codex edit and test in the workspace-write sandbox, then commits and links the actual SHA. The runner handles Git writes and posts the final result as the Codex virtual member.

Commits stay local by default. Add --allow-delivery to authorize pushing the issue branch and opening a linked PR. Delivery needs local Git authentication and the workspace’s GitHub repository mapping. The worker does not merge PRs or mark issues Done. Connecting Codex to MCP alone does not start this worker.

Models and execution controls

The worker uses the model and reasoning effort configured in your Codex account. Optional --model and --effort flags override them together with Codex’s model compatibility checks. Issue text and comments are treated as untrusted task data. Native execution is unattended, bounded to 30 minutes, and renews its server lease. If it stops, stale-run recovery marks the abandoned execution failed.

Emergency stop and concurrency apply to the Codex integration. A workspace requiring Velocity’s optional action checkpoint cannot use a native worker, because that runtime does not support the checkpoint. No checkpoint is required by default.

Use --once to process one batch, and --base-url consistently for another Velocity instance.