Troubleshooting
Fixes for the problems people most often hit setting up the Prismor runtime guard. If you're scanning repos instead, see the CLI docs — that's the separate prismor-cli tool.
Install & setup
| Symptom | Fix |
|---|---|
PyYAML is not installed (or import yaml fails) | pip3 install pyyaml, then re-run prismor setup. |
prismor: command not found after install | The console script isn't on your PATH. Add $(python3 -m site --user-base)/bin to your shell profile, then open a new terminal. |
pip install prismor succeeds but nothing works | Confirm you didn't install the wrong package — the runtime guard is prismor, not prismor-cli (that's the separate scanner tool). |
| Setup wizard doesn't appear in CI | With no terminal, prismor setup skips the wizard and installs with observe-mode defaults. Pass your choices explicitly, e.g. prismor setup --non-interactive --mode observe. |
prismor setup run by a coding agent installs nothing and prints questions | Expected. With no terminal inside an agent, setup prints the wizard's questions (mode, cloaking, scope, agents) plus the exact --non-interactive command for your answers. Answer them and let the agent run that command. |
Enrollment
| Symptom | Fix |
|---|---|
prismor enroll <token> fails with "token expired" | Enrollment tokens are single-use and expire in 24 hours. Mint a new one from Dashboard → Getting Started checklist → Enroll device. |
| Device enrolled but doesn't show up in the dashboard | Enrollment and hook installation are separate steps — enrolling reports the device to your org, but you still need prismor install-hooks for activity to appear. Give it up to ~30 seconds after enrolling. |
| Enrolled on the wrong org | Run prismor logout and re-enroll with a token minted from the correct org's dashboard. |
Hooks not firing
| Symptom | Fix |
|---|---|
| Hooks installed but nothing appears in the dashboard | You haven't run an agent session in a hooked workspace yet — the dashboard only shows activity once your agent makes a tool call under policy. |
| Hooks stopped working after an agent update | Re-run prismor install-hooks --agent claude --scope project --mode observe to rewrite the agent's settings file — some agent updates reset local config. |
| Codex hooks installed but nothing is screened | Codex skips hooks you haven't trusted. Open codex interactively once in the workspace and accept the hook-trust prompt (headless: codex exec --dangerously-bypass-hook-trust). prismor status and prismor doctor report untrusted hooks. |
Installed with --scope project but nothing happens in a different repo | Project scope only applies to the workspace you ran the install command in. Re-run it inside each project you want protected, or use --scope user for a machine-wide default. |
Secret cloaking
| Symptom | Fix |
|---|---|
| Cloak does nothing | Confirm the agent's tool call references the placeholder syntax @@SECRET:<name>@@, and that the secret is registered: prismor cloak list. |
| Secret still visible in output | Cloaking substitutes real values at execution time and scrubs them from captured output — it doesn't retroactively redact things already printed to your terminal history. |
Still stuck?
- Run
prismor doctorto health-check hooks, policy, enrollment and the telemetry sink in one go. - Check
prismor --helpandprismor install-hooks --helpfor the exact flags on your installed version. - Re-read the Quickstart — most issues are a skipped or reordered step.
- Full setup skill (with more detail than this page):
/docs/agent-setup.
Frequently asked questions
Why do I get "prismor: command not found" after installing?
The console script is not on your PATH. Add the output of python3 -m site --user-base with /bin appended to your shell profile, then open a new terminal.
Why does Prismor report that PyYAML is not installed?
The policy engine requires PyYAML. Install it with pip3 install pyyaml and then re-run prismor setup.
My enrollment token says it expired. What do I do?
Enrollment tokens are single-use and expire after 24 hours. Mint a new one from the dashboard under the Getting Started checklist, then run prismor enroll with the new token.
My device enrolled but does not show up in the dashboard. Why?
Enrollment and hook installation are separate steps. Enrolling registers the device, but you still need prismor install-hooks before activity appears. Allow up to about 30 seconds after enrolling.
How do I run Prismor setup in CI without the interactive wizard?
Use prismor setup --non-interactive --mode observe instead of the interactive wizard, so the setup completes without prompting.