Agent policy & audit log
A project's .ingot/policy.json sets hard rules for agents: commands they may never run, files they may not write, hosts they may not reach. Agent commands also run inside an operating-system sandbox on macOS and Linux, and behind the approval gate on Windows (Agent Sandbox). Every tool call an agent makes is written to a tamper-evident audit log you can browse.
The policy file
Run Agents: Open Agent Policy (.ingot/policy.json) to create the file from a template and open it. Comments and trailing commas are allowed, and changes apply from the agent's next step.
{
"commands": {
"allow": ["npm test", "npm run lint", "git status", "git diff"],
"deny": ["sudo", "rm -rf /", "git push --force", "curl * | sh"]
},
"paths": {
"writable": ["src/**", "tests/**", "package.json"],
"readOnly": [".env", ".env.*"]
},
"network": { "default": "allow", "allow": [], "deny": ["pastebin.com", "*.ngrok.io"] },
"sandbox": { "mode": "restricted", "allowWrite": ["~/.gradle"] }
}
| Field | Meaning |
|---|---|
commands.deny | refused at once, without a card; wins over allow |
commands.allow | runs without the approval card (every part of the command must match) |
paths.writable | the only files the agent may edit, create or delete; empty means the whole project |
paths.readOnly | files the agent may never change |
network.default | allow, deny or ask for hosts not listed; ask shows a Reach a new host card |
network.allow, network.deny | host patterns; github.com also covers its subdomains, *.example.com only subdomains |
sandbox.mode | restricted (default) or off |
sandbox.allowWrite | extra folders commands may write to in restricted mode (inside the OS sandbox too) |
Commit the file so every teammate's agents follow the same rules.
How patterns match
- Commands are split on
&&,||,;and|and each part is checked;git pushalso matchesgit push origin main.*matches anything. - A command with
$(…)or backticks never matchesallow, so it always gets a card. .ingot/policy.jsonand.git/are always read-only for agents.localhostis always reachable unless you deny it by name.
When the agent hits a rule
The agent gets a clear refusal and is told not to retry:
Blocked by .ingot/policy.json: it denies the command (commands.deny "git push --force"). Do not retry this; ask the user to change the policy if it is really needed.
A command that names a path outside the project (~/…, /etc/…, ../..) asks first with Run outside the project. If the file has a JSON error, agents can only read until you fix it.
Policy and sandbox presets
The sandbox preset lives in the same file under preset. A deny always wins, even with Full access. An allow only removes the usual card; the preset still checks the action.
The OS sandbox
On macOS (and on Linux with bubblewrap), with sandbox.mode at restricted (the default), every command an agent runs is started inside the system sandbox. It can read as usual, but may only write to:
- the project folder and the temp folders (
/tmp;/var/tmpon Linux) - package manager caches (
~/.npm,~/.cache,~/.yarn,~/.pnpm-store,~/.bun,~/Library/Caches) - the folders in
sandbox.allowWrite
With network.default set to deny, all outgoing traffic except localhost is blocked too. When the sandbox stops a write, Ingot offers Sandbox blocked it, run unrestricted once; skip it and the agent keeps the work inside the project. On Linux the sandbox is bubblewrap; on Windows, Ingot reads Windows paths and asks before a command leaves the project. See Agent Sandbox for each system, the allow-list and Allow in workspace.
The audit log
Every agent tool call is recorded: what it was, when, the decision (auto, policy allow, approved, always run, skipped, stopped or denied), the result and how long it took. Secrets such as API keys, tokens and passwords are replaced with [redacted] before anything is written.
The log is one file for all projects, ~/.ingot/audit/agent-audit.jsonl, outside every project so agents can't reach it. Each line includes the hash of the line before it, so editing or removing a line in the middle breaks the chain.
Browse it
Run Agents: Agent Audit Log (⌘⌥⇧A, Ctrl+Alt+Shift+A).
- The header summarizes the policy:
Commands: 4 allowed, 4 denied · Writable: src/**, tests/** · Network: allow by default, 2 blocked · Sandbox: restricted, with Edit policy. - Filter by text or decision. The badge reads
Chain intact · 128 entries, orTampered at line 57. - Columns: Time, Tool, Action, Decision, Result, Duration. Commands that ran in the OS sandbox are tagged
sandboxed. - Click a row for the reason, chat, arguments and output.
The table shows the newest 500 entries; the chain check covers the whole file.