Configuration
Environment variables, plugin settings, authentication, and managing the plugin
Configuration
Authentication
ArmorCodex works in local-only mode without any authentication. To enable backend features (audit logs, signed tokens, dashboard), you need an ArmorIQ API key.
Via Installer (recommended)
The installer prompts "Connect your ArmorIQ account now?" and runs armoriq login --product armorcodex. This opens your browser, you authorize, and the key is saved automatically. The --product armorcodex flag makes the approval page render ArmorCodex-branded heading and tagline instead of generic ArmorIQ.
Via CLI (anytime after install)
armoriq login --product armorcodex # browser-based SSO, saves key
armoriq whoami # check current auth
armoriq logout # clear credentialsManual
export ARMORIQ_API_KEY=ak_live_...Or set the API key via Codex's plugin user-config UI when self-serve install ships.
Key Resolution Order
ArmorCodex checks in this order:
ARMORIQ_API_KEYenvironment variable~/.armoriq/credentials.json(saved byarmoriq login)- No key found: local-only mode
Environment Variables
| Variable | Default | Description |
|---|---|---|
ARMORIQ_API_KEY | (none) | ArmorIQ API key |
ARMORIQ_ENV | production | Endpoint set: production, staging, or local |
ARMORCODEX_MODE | enforce | enforce blocks on failure, monitor logs only |
ARMORCODEX_INTENT_REQUIRED | true | Require intent plan for all tool calls |
ARMORCODEX_VALIDITY_SECONDS | 300 | Intent token TTL in seconds (5 min) |
ARMORCODEX_PLANNING_ENABLED | true | Inject plan directive into Codex's context |
ARMORCODEX_AUDIT_ENABLED | true | Send audit logs to backend (when key set) |
ARMORCODEX_POLICY_UPDATE_ENABLED | true | Allow runtime policy updates |
ARMORCODEX_DEBUG | false | Show debug logs in stderr |
ARMORCODEX_USE_SDK_INTENT | false | Bake-in default; set true to call the ArmorIQ SDK for token issuance during MCP register_intent_plan |
ARMORCODEX_INTENT_DEADLINE_MS | 500 | Hard cap on the SDK round-trip from inside the MCP server (avoids Codex's ~1s transport timeout) |
CSRG_VERIFY_ENABLED | false | Enable backend CSRG step verification |
REQUIRE_CSRG_PROOFS | false | Require cryptographic proofs |
ARMORIQ_ENV=local flips all SDK endpoints to localhost (127.0.0.1:3000 for backend, 127.0.0.1:3001 for proxy, 127.0.0.1:8080 for CSRG). Useful for local development against your own conmap-auto + frontend stack.
userConfig (plugin manifest)
When Codex's self-serve install ships, the plugin manifest exposes these user-facing settings:
| Setting | Type | Description |
|---|---|---|
api_key | string (sensitive) | ArmorIQ API key |
mode | string | enforce or monitor |
intent_required | boolean | Require intent plan for all calls |
crypto_policy_enabled | boolean | Enable Merkle tree policy binding |
use_production | boolean | Use production endpoints |
Managing the Plugin
ArmorCodex's installer wires [mcp_servers.armorcodex-policy] into ~/.codex/config.toml and writes ~/.codex/hooks.json. The marketplace registration is separate.
codex plugin marketplace upgrade armorcodex # pull the latest revision
codex plugin marketplace remove armorcodex # de-register
bash ~/.armoriq/armorCodex/install_armorcodex.sh --uninstall # remove hooks + MCP blockFull Uninstall
To remove everything including cached data:
bash ~/.armoriq/armorCodex/install_armorcodex.sh --uninstall
codex plugin marketplace remove armorcodex
rm -rf ~/.codex/.tmp/marketplaces/armorcodex
rm -rf ~/.armoriq/armorCodex
rm -f ~/.armoriq/credentials.jsonMonitor Mode
To observe without blocking (useful for testing):
export ARMORCODEX_MODE=monitor
codexAll enforcement events are logged but tool calls proceed normally.
Monitor mode should only be used for testing. In production, use enforce mode to actually block unauthorized tool calls.