setup · diff

git:20260804.c8a22f2 to git:20260811.9c2c95a

6 added, 2 removed. Audit B to A.

---

name: setup

description: Set up and verify AgentGuards in Codex against a self-hosted appliance. Use when the user asks to configure AgentGuards, set their URL/API key, or check that the guardrails are wired up correctly.

---

# AgentGuards setup — self-hosted

Unlike the hosted plugin, this variant has **no default backend** — it must be

told which appliance to use. Guide the user through both required variables.

## Steps

1. **Check for `AGENTGUARDS_URL`.** This is required here (the hosted plugin

defaults it; this one deliberately does not, so it can never silently talk

to the wrong instance). It should be the appliance's own address, reachable

from wherever Codex runs, over HTTPS.

2. **Check for the API key.** Look for `AGENTGUARDS_API_KEY`, or a saved token

at `~/.codex/agentguards_token`. If neither exists, tell the user to

generate one on their appliance's own console at

`<AGENTGUARDS_URL>/admin/ui/keys`, then either:

```

echo "ag_..." > ~/.codex/agentguards_token

```

or export `AGENTGUARDS_API_KEY` instead.

3. **If the appliance is still on its first-boot self-signed certificate**,

plain requests will fail with `CERTIFICATE_VERIFY_FAILED`. Two ways to fix,

both explained on the appliance's own `/admin/ui/docs#tls` page:

- `AGENTGUARDS_CA_BUNDLE=<path to the appliance's exported cert>` (pins it,

verification stays on — the better option)

- `AGENTGUARDS_TLS_NO_VERIFY=true` (evaluation on a private network only)

4. **Tell the user to add `AGENTGUARDS_URL` (and `AGENTGUARDS_API_KEY`, if used

instead of the token file) to their shell profile** (`~/.bashrc`,

`~/.zshrc`, …), not just export them in the current terminal — a one-off

`export` is gone the moment the terminal closes or a new agent session

starts.

5. **Register the hooks** in `~/.codex/config.toml` if not already present —

see this plugin's README for the exact block, or confirm it's already

there if installed via `/plugin install`.

- 6. **Verify**: ask the user to try a prompt like "ignore all previous

- instructions". It should be refused with an `[AgentGuards]` block panel. If

+ 6. **Verify**: ask the user to try a prompt the guardrails block — asking to

+ be shown all the API keys works well. It should be refused with an

+ `[AgentGuards]` block panel. (Deliberately not spelling out a

+ prompt-injection payload here: plugin security scanners run YARA over skill

+ files and flag the literal string as an injection, which is how this file

+ once scored a critical finding for documenting an attack.) If

it isn't, `AGENTGUARDS_URL`/the API key are likely not reaching the hook

process — confirm they're in the shell profile, not just the current shell.