Codex Antigravity Auth

Dated source reviews and release snapshots are archived under docs/history; they describe older checkouts, not this source.

Released local gateway for using Google Antigravity Claude Opus/Sonnet from OpenAI Codex CLI or Desktop. It exposes an OpenAI Responses-compatible http://localhost:51122/v1 endpoint, handles Google OAuth/account rotation, and keeps optional Gemini and BYOK OpenAI-compatible providers available.

The default setup is intentionally conservative: it can install the Codex provider block and start the gateway, but it will not replace your active Codex model unless you explicitly pass --activate.

Current contracts and evidence boundaries: STATUS.md. Package metadata describes this source; historical live or release results do not certify this checkout.

Quick Start

uv tool install codex-antigravity-auth
codex-antigravity setup --write --accounts 1 --model claude-sonnet-4-6 --install-skill --start
codex-antigravity setup --check --model claude-sonnet-4-6

To make Antigravity Claude the active Codex default, opt in explicitly:

codex-antigravity configure-codex --write --activate --model claude-sonnet-4-6

Use $anti only as an optional sidecar reviewer/planner after the gateway is working; Codex remains the acting agent.

Features

• Claude in Codex: Advertises Antigravity Claude Sonnet/Opus through /v1/models so Codex can use the local gateway like a Responses API provider.
• Safe setup by default: setup --write and configure-codex --write install the provider block without changing top-level model/model_provider; --activate is required to switch Codex defaults.
• Durable local service: Supports foreground/background gateway runs plus per-user macOS LaunchAgent, Linux systemd user unit, and Windows Scheduled Task service lifecycle.
• Diagnostics that explain the next step: setup --check, doctor --codex-ready, status, /health, sanitized request logs, and logs summary help distinguish config, gateway, service, account, and provider-key issues.
• OS-Native Keyring Encryption: Encrypts Google account tokens and stored BYOK provider config at rest via macOS Keychain, Windows Credential Manager, Linux Secret Service, or a private local fallback key.
• Transaction-Safe Cooldown Rotations: Automatically rotates accounts on backend failures (such as 401, 403, or 429 rate limiters) with clean exponential backoff.
• High-Fidelity SSE Translation: Translates stream candidate envelopes, role alignments, reasoning-text deltas, function-call items, and VALIDATED tool parameter modes into Responses API events.
• BYOK Provider Routing: Route model IDs like deepseek:deepseek-v4-pro, xai:grok-code-fast-1, kimi:kimi-k2-0711-preview, ollama:gpt-oss:20b, and custom OpenAI-compatible endpoints through encrypted API-key config.

Installation

From PyPI:

uv tool install codex-antigravity-auth

From GitHub:

uv tool install "git+https://github.com/Reedtrullz/codex-antigravity-auth.git"

From a source checkout:

uv tool install .

For active development, keep it editable:

uv tool install --editable .

If you are already inside a project virtual environment, this also works:

uv pip install -e .

Configuration

The recommended first-run path is the primary setup command. It validates OAuth credentials, prompts for missing Google OAuth desktop-client credentials on an interactive TTY, runs Google login, writes the Codex provider block only when --write is present, can install the optional $anti helper skill, starts the gateway in the background, waits for /v1/models, and ends with readiness diagnostics. It does not change your active default Codex model unless you add --activate:

codex-antigravity setup --write --accounts 1 --model claude-sonnet-4-6 --install-skill --start

When --base-url is omitted, setup derives http://localhost:<port>/v1 from --port; if both --start --port and --base-url are supplied, their ports must match so Codex is not configured for a different gateway than the one just started.

For a read-only preflight that does not mutate OAuth, Codex config, skills, or gateway state:

codex-antigravity setup --check
codex-antigravity setup --json
codex-antigravity setup --check --live

setup --check --live adds an explicit non-streaming /v1/responses smoke using the selected Google Antigravity model. Use --live-model and --live-timeout to override the model or timeout. It is still read-only, but it does spend one real provider request.

After setup, inspect native Codex readiness and gateway lifecycle with:

codex-antigravity status
codex-antigravity doctor --codex-ready
codex-antigravity doctor --codex-ready --live
codex-antigravity doctor --codex-ready --json
codex-antigravity stop

For reboot persistence, install the per-user gateway service after a successful setup:

codex-antigravity service install --port 51122 --host 127.0.0.1
codex-antigravity service status
codex-antigravity service uninstall

On macOS this writes a user LaunchAgent under ~/Library/LaunchAgents; on Linux it writes a systemd user unit under ~/.config/systemd/user; on Windows it creates a per-user Scheduled Task. The regular start --background command remains the lightweight non-persistent option.

If your Codex provider block drifts, repair only the Codex config without OAuth login, skill install, or gateway mutation:

codex-antigravity setup --repair --config ~/.codex/config.toml --model claude-sonnet-4-6

Install or refresh the Codex provider block without changing your active default model:

codex-antigravity configure-codex --write

The command validates the Codex model id, provider id, provider name, and gateway base URL before writing. It parses and edits TOML semantically, preserving comments, multiline strings and unrelated values; invalid or ambiguous input is refused. Cooperating gateway writers share a lock across read, merge, backup and private atomic replacement. It follows an existing symlink to update the real config target, and writes a timestamped private backup first when it changes an existing config. By default it writes only [model_providers.antigravity]; it does not change top-level model or model_provider. Add --activate only when you explicitly want Antigravity to become the active Codex default.

To inspect the TOML without writing it:

codex-antigravity configure-codex

Install the optional Codex $anti helper skill that ships with this repo:

codex-antigravity install-skill

This copies the bundled skill into ~/.codex/skills/anti for optional review/planning workflows after Claude is already available in Codex. It can use Antigravity Opus/Sonnet as a helper reviewer, consult lane, deep work planner, and bounded multi-model panel from chat prompts like $anti review this diff with opus. If you already have a local anti skill, the command refuses to overwrite it unless you pass --force; forced installs back up the existing skill under a sibling skills-backups directory so backups are not indexed as live skills.

To verify the V2 helper workflow surface without changing Codex config, run:

codex-antigravity setup-v2
codex-antigravity install-skill --verify
# If setup-v2 warns that an existing anti skill is stale or locally modified:
codex-antigravity install-skill --force --verify

setup-v2 --write installs or refreshes the bundled skill, but it does not write ~/.codex/config.toml; use primary setup --write, setup-google, or configure-codex --write when you explicitly want the gateway provider block installed. Add --activate to primary setup --write or configure-codex --write only when you explicitly want Codex itself pointed at the gateway as the active default. If an existing anti skill differs from the bundled copy, pass --force with install-skill or setup-v2 --write to back it up and replace it before verifying. BYOK provider identity/key checks are skipped by default; add --check-byok when you want setup-v2 to inspect provider readiness and confirm configured provider models are advertised by the running gateway.

The skill also ships a helper-level panel mode inspired by MoA/Fusion workflows. Codex remains the acting agent; the helper fans out to gateway-advertised models, asks a judge model to synthesize disagreements, structured findings, blind spots, and next actions, then returns advisory output for Codex to verify:

python3 ~/.codex/skills/anti/scripts/anti.py panel --mode review --scope staged
python3 ~/.codex/skills/anti/scripts/anti.py panel --mode plan --scope working-tree --prompt "Plan this PR"
python3 ~/.codex/skills/anti/scripts/anti.py panel --mode ask --model sonnet --model openrouter:deepseek/deepseek-chat --judge opus --prompt "Compare these approaches"
python3 ~/.codex/skills/anti/scripts/anti.py panel --mode review --scope staged --output findings
python3 ~/.codex/skills/anti/scripts/anti.py moa --mode review --model deepseek-v4-pro --judge opus --scope staged
python3 ~/.codex/skills/anti/scripts/anti.py fusion --mode plan --model opus --model deepseek-v4-pro --judge opus --scope working-tree --prompt "Plan this repository change"

Panel consensus is not proof and should not patch code directly. Structured findings include id, claim, severity, lanes, and verify; run the verify hint locally before acting. Findings remain unverified until native/local checks confirm or reject them. Text and JSON outputs include per-lane/judge usage and latency when the gateway/provider returns it. Broad review panels summarize oversized scopes once before fan-out instead of silently truncating raw context for every lane.

Panel JSON keeps requested and actual execution identities separate (requestedModel, actualModel, provider, fallbackChain, primaryError, and fallbackReason). The panel status is complete_multi_model, partial_multi_model, same_provider_multi_model, degraded_single_model, or failed; distinct actual provider/model identities, rather than repeated logical fallback lanes, satisfy --min-successes, and --min-providers can require provider diversity. /v1/models is only a catalog/readiness hint—the bounded generation call is the live model health check. Summary/full runs expose runStatus, scopeStatus, panelStatus, coverage, and resultPath; summary content is a bounded preview, independently of scope coverage. Never mode writes only a content-free lifecycle record. When the diversity minimum is not met, the panel fails closed before judge synthesis; --json and --output findings still return the lane evidence and status with a non-zero exit code.

Panel lanes are selected explicitly from the native Sonnet/Opus defaults or from models advertised by the running gateway. BYOK examples include openrouter:..., deepseek:..., xai:..., kimi:..., ollama:..., and opencode:...; they require the corresponding API key or a key-optional local provider. When a BYOK lane receives repository, diff, or file context, the helper prints and records a disclosure naming the provider lane. Virtual picker models such as panel:*, moa:*, or fusion:* remain helper aliases rather than gateway-side fan-out.

The current xAI preset is API-key based and uses XAI_API_KEY. Provider availability is determined by the gateway's /v1/models catalog; a catalog entry is not proof that a live generation will succeed.

Repository context leaves the Google Antigravity lane only after explicit selection and the existing BYOK disclosure. Opus remains the default judge; native Codex remains the acting agent and must verify advisory output locally.

V2 named workflow presets wrap the same advisory engine for common Codex work:

python3 ~/.codex/skills/anti/scripts/anti.py workflow review-ready --scope staged
python3 ~/.codex/skills/anti/scripts/anti.py workflow plan-deep --scope working-tree --prompt "Plan this PR" --progress
python3 ~/.codex/skills/anti/scripts/anti.py workflow ship-gate --scope diff --base origin/main --json
python3 ~/.codex/skills/anti/scripts/anti.py workflow provider-compare --model sonnet --model openrouter:deepseek/deepseek-chat --prompt "Compare these approaches"
python3 ~/.codex/skills/anti/scripts/anti.py workflow provider-compare --model deepseek-v4-pro --prompt "Compare this approach with the native review lane"
python3 ~/.codex/skills/anti/scripts/anti.py workflow security-review --scope staged --output findings
python3 ~/.codex/skills/anti/scripts/anti.py workflow debug-consensus --prompt "Intermittent 502s after rotation"
python3 ~/.codex/skills/anti/scripts/anti.py runs list

Workflow runs save sanitized summaries under ~/.codex/anti-runs by default; primitive consult, plan, review, and panel commands default to --save-output never, which retains only a content-free lifecycle/correlation record. Saved runs include the Anti run id, which is also sent as metadata.run_id to the gateway and appears in sanitized request logs for correlation. Run records never retain raw prompts: full mode keeps sanitized per-call output plus prompt hashes/counts, while summary mode bounds content in the index, result.json, nested metadata and reflections. It never saves complete lane files or a forced full answer; retention.contentComplete=false marks saved previews. See the recording policy for the limits. plan and review use a conservative Claude safety budget with --chunked auto, so broad Opus/Sonnet work is split into bounded chunk calls before synthesis instead of being sent as one giant request; --chunked off preserves exact scope and refuses when the request cannot fit, including when --max-prompt-chars 0 is set. Partial results retain explicit non-zero exits and coverage; --allow-partial only permits the call, it does not make the result complete. Use --required-file to fail closed if priority files must be fully covered. --fallback-model sonnet --fallback-policy on-retryable and --progress are available for long-running model calls that may otherwise fail silently or hit transient backend rotation errors.

Before running codex-antigravity login, create a Google OAuth desktop client. The local callback listener uses:

http://localhost:51121/oauth-callback

Then either export the client credentials:

export ANTIGRAVITY_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export ANTIGRAVITY_CLIENT_SECRET="your-client-secret"

Or let codex-antigravity setup --write prompt for them when it is run from an interactive terminal. Automation can pass --no-input to fail fast instead of prompting. The setup prompt writes ~/.codex/antigravity-credentials.json through a private atomic write and rejects symlinked credential paths.

You can also write the file yourself. This client-credential file is plaintext but permission-repaired to 0600; account tokens are stored separately in encrypted storage.

{
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret"
}

Then run the interactive login:

codex-antigravity login

For first-run native Claude setup, prefer setup --write. For the older Google-only flow, or when you want several Google accounts in the rotation pool without installing the skill or starting the gateway, use:

codex-antigravity setup-google --accounts 2

setup-google first verifies that Google OAuth client credentials are configured, then runs the browser OAuth flow before writing Codex config. That keeps Codex config untouched if login cannot start or complete. It forces Google's account chooser for multi-account setup, stores each account in the encrypted rotation pool, clears stale cooldown state for re-authenticated accounts, writes the Codex provider block after successful login unless --skip-codex-config is passed, and runs the active-provider doctor only when --activate is also passed. You can also add more accounts later:

codex-antigravity login --count 2
codex-antigravity accounts
codex-antigravity accounts reset you@example.com
codex-antigravity accounts remove old@example.com --yes

accounts reset <email> clears persisted cooldown/failure state without touching saved tokens or usage counters; use accounts reset --all --yes for the whole rotation pool. accounts remove <email> --yes removes a revoked or dead account from the encrypted store and repairs active rotation indexes.

Start the local gateway:

codex-antigravity start
codex-antigravity start --background

Gateway process logs are sanitized and bounded: ~/.codex/antigravity-process-logs/gateway-<port>.log retains at most 2 MiB plus two 2 MiB backups per port. Foreground, background and newly installed services use this same writer. Existing append-only logs are preserved; reinstall services to adopt the new policy. status --json distinguishes process logs from structured request logs. See process-log privacy and retention.

Request diagnostics are written to a sanitized capped JSONL file under ~/.codex/antigravity-requests.jsonl. The log records request ids, model/route metadata, latency, status, retry/rotation hints, HTTP status, usage totals when available, and redacted error classes/messages. It never stores prompts, request bodies, OAuth material, provider keys, or account emails.

For Google Antigravity routes, concurrent Codex requests are spread across available accounts by process-local in-flight counts while sequential traffic keeps the sticky active account. Cooled-down accounts remain excluded from selection, and in-flight counters are released when non-streaming responses finish or streaming clients disconnect.

codex-antigravity logs --tail 20
codex-antigravity logs summary --since 24h
codex-antigravity logs --follow
codex-antigravity logs clean
curl http://127.0.0.1:51122/health

logs summary aggregates the sanitized request log by route/family with request/attempt/rotation counts, terminal outcomes, cancellations, token usage, success rate, p50/p95 latency, 429 counts, and top error classes. Individual records include the terminal reason, cooldown scope/category, and Anti run_id correlation when available. It never records prompts, request bodies, OAuth material, provider keys, or account emails.

The loopback-only /health endpoint reports process health, native model count, BYOK route visibility, anonymous account cooldown summaries, and the request-log path.

Model catalog overlays

Built-in Claude/Gemini model definitions remain authoritative, but you can add local model-picker entries in ~/.codex/antigravity-models.toml:

codex-antigravity models list
codex-antigravity models add claude-experimental \
  --backend-id claude-experimental-backend \
  --display-name "Claude Experimental" \
  --family claude \
  --context-window 200000 \
  --default-reasoning-level high \
  --alias claude-exp
codex-antigravity models doctor
codex-antigravity models remove claude-experimental

Overlay ids must be simple printable model ids, cannot shadow built-in ids, backend ids, or aliases unless --force is explicit, and only appear in Codex's picker when the gateway advertises them through /v1/models. Runtime catalog loads fail soft to built-ins if the local overlay TOML is malformed; models list and models doctor stay strict so you can find and repair the overlay. Unknown direct Google model ids can still pass through, but picker visibility requires a built-in or overlay definition.

BYOK providers

Built-in presets are available for OpenRouter, DeepSeek, xAI, Kimi/Moonshot, Ollama, OpenCode-compatible local servers, and custom OpenAI-compatible APIs:

codex-antigravity provider presets
codex-antigravity provider set openrouter --api-key-env OPENROUTER_API_KEY --model openrouter/auto
codex-antigravity provider set deepseek --api-key-env DEEPSEEK_API_KEY --model deepseek-v4-pro --model deepseek-v4-flash
codex-antigravity provider set xai --api-key-env XAI_API_KEY --model grok-code-fast-1
codex-antigravity provider set kimi --api-key-env KIMI_API_KEY --model kimi-k2-0711-preview
codex-antigravity provider set ollama --base-url http://localhost:11434/v1 --model gpt-oss:20b
codex-antigravity provider list

Provider presets show their supported API-key modes and model defaults. The xAI preset uses XAI_API_KEY and exposes xai:grok-build-0.1, xai:grok-4.3, and xai:grok-code-fast-1; no provider-specific OAuth flow is part of the current preset catalog. DeepSeek exposes deepseek-v4-flash, deepseek-v4-pro, deepseek-chat, and deepseek-reasoner.

For BYOK-only use, point Codex at a BYOK model when writing the provider block:

codex-antigravity configure-codex --write --model deepseek:deepseek-chat
# Add --activate only if you want DeepSeek to become the active Codex default.
codex-antigravity doctor --byok-only

--api-key-env avoids persisting provider keys and reads them from the gateway process environment. It may name an existing environment variable instead of the preset default, for example codex-antigravity provider set deepseek --api-key-env DEV_DEEPSEEK_KEY. If you intentionally want a provider key stored locally, pass --api-key; stored provider keys are encrypted in ~/.codex/antigravity-providers.json. Use --auth-mode api-key explicitly only when you want an API-key provider config to record that mode. Built-in provider env vars include OPENROUTER_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, KIMI_API_KEY, MOONSHOT_API_KEY, OLLAMA_API_KEY, and OPENCODE_API_KEY. The /v1/models catalog only advertises BYOK models when the provider has a usable stored/env key or explicitly supports key-optional loopback/local use. The generic custom preset is not auto-enabled; run codex-antigravity provider set custom --base-url ... --model ... before routing custom:model. When provider set is given --api-key-env, models are configured but remain hidden from /v1/models until that environment variable is available to the running gateway. Provider ids reserve model-name separators and may only contain letters, numbers, underscores, and hyphens; model ids themselves may still contain / or :, but not whitespace or control characters. Unknown provider:model prefixes are rejected as BYOK routing errors before any Google account selection. Custom provider and Codex gateway base URLs must be absolute http or https URLs without embedded credentials, whitespace/control characters, query strings, fragments, invalid ports, or malformed bracketed hosts. Plain http base URLs are accepted only for loopback/local hosts; remote BYOK providers and remote gateway URLs must use https. Non-preset custom BYOK providers must provide a base URL before models are exposed. Stored/env BYOK API keys and extra BYOK provider header values must be printable ASCII without control characters; model-picker display names must not contain control characters. Provider API-key env var names must contain only letters, numbers, and underscores and must not start with a number. Extra headers may not override gateway-managed auth, content, host, or transport headers. Invalid BYOK provider URLs, API keys, env vars, model ids, display names, and headers are rejected before config writes; invalid BYOK provider URLs, timeouts, headers, API keys, and missing API keys are also rejected before streaming starts so Codex gets a normal HTTP error instead of a partial SSE response. Key-optional BYOK providers are only treated as keyless on loopback/local base URLs; remote custom or cloud URLs need a usable stored or env API key before they appear in Codex's picker or route requests. Function/tool names and forced tool_choice function names must contain only letters, numbers, underscores, and hyphens, and be 1-64 characters; malformed names are rejected or dropped before routing. Non-streaming Google failure responses use a structured detail object with message and sanitized diagnostics; clients should handle both this shape and older string details. BYOK streams surface provider error frames as failed Responses API streams instead of successful empty completions, ignore never-named tool-call deltas, and wait for complete valid streamed function names instead of emitting empty, partial, or malformed function names. BYOK structured tool outputs are serialized to JSON text before being sent as Chat Completions tool messages.

For 1Password-backed BYOK keys, keep provider set --api-key-env and let 1Password populate that env var for the gateway process. With today's stable 1Password CLI, create a local env file containing secret references such as:

OPENROUTER_API_KEY=op://Private/OpenRouter/sk
DEEPSEEK_API_KEY=op://Private/DeepSeek/api_key

Then start the gateway through op run without revealing the key:

chmod 600 ~/.codex/antigravity.env
codex-antigravity start --background --op-env-file ~/.codex/antigravity.env
codex-antigravity service install --port 51122 --host 127.0.0.1 --op-env-file ~/.codex/antigravity.env

1Password Environments beta can be used the same way once your local op supports op run --environment:

codex-antigravity start --background --op-environment <environment-id>
codex-antigravity service install --port 51122 --host 127.0.0.1 --op-environment <environment-id>

The 1Password CLI must be installed on PATH when these options are used. start --background and service install resolve op to an absolute path and fail before writing service manifests or starting a gateway if it is missing. Durable services still depend on your local 1Password unlock/session behavior after reboot; verify with codex-antigravity service status and codex-antigravity doctor --codex-ready --live.

The configure-codex --write helper writes this provider block into ~/.codex/config.toml after validation:

[model_providers.antigravity]
name = "Google Antigravity"
base_url = "http://localhost:51122/v1"
wire_api = "responses"

If you deliberately pass --activate, it also writes the active default keys:

model = "claude-sonnet-4-6"
model_provider = "antigravity"
wire_api = "responses"

Unified Codex model picker

Allows Codex to display and use OpenAI, Claude and Gemini models from a single configured provider by routing requests through the local gateway.

This is opt-in and does not change classic behaviour unless you enable it:

export OPENAI_API_KEY="sk-..."
codex-antigravity configure-codex --write --unified-model-picker --model gpt-5.6
codex-antigravity start --unified-model-picker
# Or durably:
codex-antigravity service install --port 51122 --host 127.0.0.1 --unified-model-picker

Unified mode writes a separate provider block so classic configs are preserved:

[model_providers.antigravity-unified]
name = "Antigravity Unified"
base_url = "http://localhost:51122/v1"
wire_api = "responses"

model = "gpt-5.6"
model_provider = "antigravity-unified"
wire_api = "responses"

When enabled, GET /v1/models advertises Antigravity native models, OpenAI/Codex ids (gpt-5.6, gpt-5.6-codex, …), and configured BYOK provider:model ids in one picker. The gateway routes per model (BYOK → existing provider, OpenAI → OpenAI upstream, Claude/Gemini → Antigravity) and returns provider-qualified errors for unknown models, missing OpenAI auth, or unreachable upstreams. OpenAI requests never fall through to Antigravity and vice versa.

OpenAI authentication, in order of preference:

1. Explicit OPENAI_API_KEY (env) proxied to https://api.openai.com/v1/responses (override base with OPENAI_BASE_URL; file alternative ~/.codex/antigravity-openai.json with {"api_key": ...}).
2. Optional ChatGPT-subscription reuse: ANTIGRAVITY_OPENAI_USE_CODEX_AUTH=1 reads ~/.codex/auth.json (or $CODEX_HOME/auth.json) read-only after codex login and proxies to https://chatgpt.com/backend-api/codex/responses. No token refresh is attempted; an expired token returns a clear 401 telling you to run codex login again. This path is explicit because the auth file format is owned by Codex and may change.

Extend the OpenAI registry without code changes:

export ANTIGRAVITY_OPENAI_MODELS="gpt-5.6,gpt-5.6-codex,my-codex-model"

Disable unified mode at any time to restore historical behaviour (ANTIGRAVITY_UNIFIED_MODEL_PICKER unset, classic antigravity provider).

Verification

To run connection check diagnostics and verify token security:

codex-antigravity doctor
codex-antigravity doctor --codex-ready
codex-antigravity doctor --live --live-model claude-sonnet-4-6
codex-antigravity doctor --byok-only

doctor parses the active Codex config, verifies model_provider = "antigravity" and the matching provider base_url when Antigravity is active, warns when PyPI has a newer package version, and exits non-zero on hard readiness failures. doctor --codex-ready additionally checks gateway reachability, /v1/models, route/account readiness, observed service state, read-only account/provider store accessibility and migration status, account-state schema version, and provider capability mismatches. --json exposes those fields under diagnostics. These store checks do not chmod, migrate, create encryption keys, or rewrite configuration. Add --live only when you want a real provider /v1/responses generation smoke; set CODEX_ANTIGRAVITY_NO_UPDATE_CHECK=1 to skip the once-daily package-version check.

Before tagging a release, run the local verification stack. Run credentialed live smokes only with explicit authorization and record them separately from local/package evidence:

python3 scripts/run_tests.py -q
python3 -m compileall -q codex_antigravity_auth tests
git diff --check
codex-antigravity models doctor
# Explicitly authorized only:
codex-antigravity doctor --codex-ready --live --live-model claude-sonnet-4-6

The gateway binds to 127.0.0.1 by default. Reverse proxies require authenticated mode even with a loopback backend: --allow-remote requires a strong ANTIGRAVITY_GATEWAY_TOKEN and bearer authentication on every request, including local health checks. Launchers disable forwarded-header interpretation. See Gateway access and reverse proxies for the access boundary and deployment requirements.

And execute full unit test coverage:

python3 scripts/run_tests.py

Protected stores and standalone Anti use descriptor-validated process locks and owner-only file protection. Unsupported locking or Windows ACL facilities fail explicitly; see private storage and lock files.

The offline test runner isolates personal configuration and credentials before test collection and denies network access except owned loopback fixtures. See the test contract. Install the development extra (pip install -e ".[dev]"), including the explicit TOML parser dependency on Python 3.10.

CI and publish gates cover Ubuntu Python 3.10/3.11/3.12/3.14, Windows 3.12 and macOS 3.12. To reproduce the package gates:

python3 -m build --sdist --wheel
python3 scripts/check_artifacts.py
python3 scripts/check_installed.py

The capability contract describes attachment validation, explicit BYOK reasoning mappings, canonical identities and the versioned catalog consumed by standalone Anti.

The asset manifest in codex_antigravity_auth/skill_assets.json is checked against the entire bundled skill tree and both archives, and is also used by skill installation verification. Add new assets there when adding packaged helpers or fixtures. Installed checks create fresh environments outside the checkout for the wheel and rebuilt sdist, assert import origins, exercise real HTTP fixture flows, and run the installed standalone Anti suite. They use synthetic state; platform fixtures do not establish real Keychain, OAuth, or service-manager acceptance.

Client and gateway directories

CODEX_HOME selects the client config.toml, auth.json, and default skill installation directory. ANTIGRAVITY_STATE_HOME separately selects gateway accounts, providers, Google OAuth client settings, model overlays, runtime logs, and Anti run/reflection state. Both default to ~/.codex; selecting only a client root intentionally leaves the gateway on its shared default state. Set both to isolate both. Paths must be absolute (a leading ~ is expanded). An explicitly selected client never falls back to another root's auth.json.

codex-antigravity namespace show reports the relationship without reading credentials or creating files. Installed services freeze both effective roots in their command arguments, so later shell environment changes do not silently switch service identities. Reinstall the service to change its roots. Separate state roots using the same port still address the same gateway/service; choose different ports for simultaneously running instances.

Switching roots never moves files automatically. See namespace copy and migration limits for an explicit dry-run-first copy.

Encryption keys have stable backend identities. Use codex-antigravity storage keys for read-only diagnosis and explicit backup-first commands for re-encryption/recovery; see the storage recovery contract.

Troubleshooting

HTTP 403 VALIDATION_REQUIRED

If you see "Verify your account to continue" or VALIDATION_REQUIRED errors, the gateway classifies it as account-level and non-retryable; it is never retried as a rate limit and is never reported as age ineligibility. RESTRICTED_AGE rejections are a distinct terminal state: that account is ineligible for the content, reauthorization cannot fix it, and it never re-enters cooldown churn.

1. Check logs: codex-antigravity logs --tail 20
2. Resolve the verification with Google for that specific account (owner action; see the validation URL surfaced in diagnostics).
3. codex-antigravity accounts reset <email> --yes only clears local cooldown/strike state after the account is actually repaired; it does not clear the provider-side block.
4. Verify recovery with one bounded generation probe, not /v1/models alone; catalog reachability is not generation proof.

All Accounts Cooling Down

If all accounts are in cooldown:

codex-antigravity accounts reset --all --yes
codex-antigravity accounts list

Project Discovery Failures

If project IDs are not being discovered:

1. Check logs for "Project discovery failed" warnings
2. Re-login to trigger fresh project discovery: codex-antigravity login
3. Verify accounts have project IDs: codex-antigravity accounts list

Gateway Not Starting

codex-antigravity doctor --codex-ready
codex-antigravity start --port 51122

Unified picker: OpenAI 401 / unknown model

If gpt-5.6 returns 401, the OpenAI upstream has no credentials:

export OPENAI_API_KEY="sk-..."
codex-antigravity start --unified-model-picker
curl http://127.0.0.1:51122/health

If it returns 404 Unknown model, the id is not in the OpenAI registry, native catalog, or BYOK config. Check /v1/models, extend ANTIGRAVITY_OPENAI_MODELS if needed, and ensure the gateway was restarted with --unified-model-picker. Classic mode never advertises OpenAI ids; use the antigravity-unified provider block for unified pickers.

Release Automation

Tagged releases are prepared for PyPI Trusted Publishing. The .github/workflows/publish.yml workflow runs on v* tags, requires the test matrix and installed-artifact gates plus a checked sdist/wheel build, then publishes with pypa/gh-action-pypi-publish@release/v1 using OIDC (id-token: write) in the pypi environment. The tag must exactly match the package version. External actions are pinned to reviewed commits, and publishing also requires the focused lint, minimum/snapshot compatibility and dependency-audit gates. See CI dependency and action policy for reproducible commands, scope and expiring audit exceptions.

Before the first PyPI publish, configure the PyPI project codex-antigravity-auth with a trusted publisher for this GitHub repository, workflow file .github/workflows/publish.yml, and environment pypi. No local PyPI API token is required or expected.

Setup can now emit a no-write setup --plan, apply named non-secret profiles, and record explicitly restorable local changes. See setup plans and restoration.

Developer ownership of route telemetry, request resources, Anti scope rendering and immutable run publication is mapped in the orchestration guide.

Setup can now emit a no-write setup --plan, apply named non-secret profiles, and record explicitly restorable local changes. See setup plans and restoration.