Skip to main content

​
Troubleshooting

Start with: 
termyte doctor

​
Agent executable was not found

Check the launch plan: 
termyte run --dry-run codex
Install the requested agent and confirm its executable is on PATH. Supported names are codex, claude, claudecode, and aider.

​
An agent launches but its commands are not intercepted

This is expected with the current limited agent runner. termyte run <agent> prepares local policy, logs, memory, and session context, but does not guarantee subprocess interception. Use termyte shell to evaluate the experimental governed shell, and verify it first with termyte doctor.

​
A policy file is rejected

Review the effective policy and error: 
termyte policy show
YAML policy supports a constrained schema:
  • version: 1;
  • known preset names;
  • rules with name, optional description, action, and match;
  • matcher groups semantic_ids, commands, and paths.
Unknown fields, malformed YAML, empty matchers, and unknown presets fail loading.

​
A plain-English policy is unsupported

The natural-language compiler supports fixed templates, not arbitrary language. Use: 
termyte policy local add "<rule>" --dry-run
If it is rejected, write the YAML rule directly. See policy examples.

​
YAML policy and runtime policy disagree

They are separate policy surfaces. 
termyte policy show
termyte policies
termyte policies status
  • policy commands manage built-in/global/repository YAML used by check.
  • policies commands manage SQLite semantic lists used by run -- and shell.

​
Check logs are empty

Only termyte check writes .termyte/logs.jsonl. policy test, logs, memory, and the experimental SQLite runtime do not write stable check events. Use termyte replay for the runtime ledger.

​
A command was unexpectedly allowed

Unknown or obfuscated command forms can fall back to a generic shell action.
  1. Inspect it with termyte check "<command>" --json.
  2. Add a global or repository policy rule.
  3. Test the rule with termyte policy test.
  4. Do not rely on Termyte as a sandbox for untrusted commands.

​
A shim blocks because the guard is unavailable

The governed shell fails closed when an intercepted command cannot reach the local guard. Exit the failed session, run termyte doctor, and start a new termyte shell. Do not bypass the block until you understand why the guard failed.

​
Runtime policies are stale

termyte policies status
Termyte reports drift without replacing customized policy. Review the missing defaults, then either keep the customization intentionally or run: 
termyte policies reset
Reset replaces the active runtime policy with current defaults.