Configuration

ArmorCopilot reads configuration in this order (later wins):

Compiled defaults from the SDK (@armoriq/sdk-dev)
Plugin userConfig set in Copilot CLI
Process env vars (ARMORCOPILOT_*)
Per-hook env block in hooks/hooks.json

Plugin userConfig

After install, open the plugin's userConfig from Copilot (copilot plugin configure armorcopilot) and set:

Field	Type	Default	Notes
`api_key`	string	(empty)	Your ArmorIQ API key. Required. Get one at https://armoriq.ai.
`mode`	string	`enforce`	`enforce` (block on policy/intent failures) or `monitor` (log only).
`intent_required`	boolean	`true`	Require every tool to be backed by a registered intent plan. Disable for advisory-only use.
`crypto_policy_enabled`	boolean	`false`	Bind policy rules to a Merkle tree (CSRG proofs).
`use_production`	boolean	`false`	When true, talks to production endpoints. When false, expects local backend on 127.0.0.1 (development).

Plugin config is stored at ~/.copilot/plugin-data/armorcopilot/armorcopilot/config.json.

Env vars

For automation / CI / per-session overrides, use process env vars:

Env var	Default	What it controls
`ARMORIQ_ENV`	`staging` (from sdk-dev)	One of `production`, `staging`, `local`. Drives endpoint defaults below.
`ARMORCOPILOT_BACKEND_ENDPOINT`	resolved from env	Override backend URL.
`ARMORCOPILOT_IAP_ENDPOINT`	resolved from env	Override IAP / CSRG URL.
`ARMORCOPILOT_PROXY_ENDPOINT`	resolved from env	Override proxy URL.
`ARMORCOPILOT_MODE`	`enforce`	`enforce` or `monitor`.
`ARMORCOPILOT_INTENT_REQUIRED`	`true`	Same as plugin userConfig field.
`ARMORCOPILOT_DATA_DIR`	`~/.copilot/armorcopilot`	Where policy.json, audit/, pending-plan files live.
`ARMORCOPILOT_DEBUG`	`false`	Enable verbose `[armorcopilot]` stderr logs.
`ARMORCOPILOT_VALIDITY_SECONDS`	`600`	Lifetime of an issued intent token (10 min default).
`ARMORCOPILOT_TIMEOUT_MS`	`8000`	HTTP timeout for backend calls.
`ARMORCOPILOT_MAX_RETRIES`	`1`	Backend retry count.
`ARMORCOPILOT_AUDIT_ENABLED`	`true` (if api_key set)	Enable audit log shipping.
`ARMORCOPILOT_USE_SDK_INTENT`	`true`	Issue intent tokens via the ArmorIQ backend.
`ARMORIQ_API_KEY`	(reads `~/.armoriq/credentials.json`)	Override the API key.

Endpoint resolution

Backend endpoints resolve based on ARMORIQ_ENV:

`ARMORIQ_ENV`	Backend	IAP	Proxy
`production`	`https://api.armoriq.ai`	`https://iap.armoriq.ai`	`https://proxy.armoriq.ai`
`staging` (default for sdk-dev)	`https://staging-api.armoriq.ai`	`https://iap-staging.armoriq.ai`	`https://cloud-run-proxy.armoriq.io`
`local`	`http://127.0.0.1:3000`	`http://127.0.0.1:8000`	`http://127.0.0.1:3001`

Explicit ARMORCOPILOT_*_ENDPOINT env vars always win.

Data directory layout

~/.copilot/armorcopilot/
├── policy.json                       # Current policy rules + version
├── runtime.json                      # Session state, runtime metadata
├── pending-plan.<session_id>.json    # Per-session registered intent plan
├── pending-plan.json                 # Legacy global path (mirror for compat)
└── audit/
    ├── audit.wal                     # Pre-flush write-ahead log
    └── archive/                      # Shipped & rolled-over WAL segments

Everything except ~/.armoriq/credentials.json lives here. Wipe the directory to fully reset state.

Debugging

Enable verbose logging:

ARMORCOPILOT_DEBUG=true copilot

Then watch the Copilot CLI log:

RECENT_LOG=$(ls -t ~/.copilot/logs/*.log | head -1)
tail -F "$RECENT_LOG" | grep -E "armorcopilot|hook="

You should see lines like:

[armorcopilot] hook=SessionStart
[armorcopilot] session started: <uuid>, mode=enforce
[armorcopilot] hook=UserPromptSubmit
[armorcopilot] hook=PreToolUse

Copilot CLI marks hook stderr output with [ERROR] level in its logs even for normal INFO lines. Don't be alarmed by [ERROR] [armorcopilot] hook=.... That's expected. Real errors say error=... in the message.

Uninstall

bash ~/.armoriq/armorCopilot/install_armorcopilot.sh --uninstall

Removes the plugin + marketplace registration. Plugin source at ~/.armoriq/armorCopilot is left in place. Run rm -rf ~/.armoriq/armorCopilot to remove fully.

Credentials at ~/.armoriq/credentials.json are preserved across uninstall/reinstall by default.

Configuration

Configuration

Plugin userConfig

Env vars

Endpoint resolution

Data directory layout

Debugging

Uninstall

On this page