FAQ

General

Is grith a sandbox?

No. grith decides whether a syscall runs; the kernel still runs it. The agent works against the real filesystem, network and OS - no isolation, no network namespace, no privilege drop.

For hard isolation, run grith inside a container or a user namespace; the two are complementary. Limitations lists what grith does not stop.

Does grith need root?

No. grith uses ptrace on processes it spawns itself, which needs either CAP_SYS_PTRACE or a Yama ptrace_scope of 0 or 1. The Debian/Ubuntu default of 1 is fine.

Does grith slow my agent down?

Startup costs about 200 ms per supervised launch - PTY allocation, ptrace attach, seccomp install. Steady state is cheaper: most syscalls never reach the proxy at all and cost typically under 50 µs; only the ones that do reach it cost a few milliseconds. Those figures were measured in March 2026 on a 0.1.x build and have not been re-measured for v0.3.1; Performance tuning has the caveats.

Can grith see my source code or my prompts?

grith does not read file contents. read, write and writev are never trapped - grith judges what is touched, not what is transferred, and a FileWrite record hashes the path rather than the data.

Prompts and model responses are between your agent and its provider - grith is not in that conversation. The exception is the built-in agent (grith run and the REPL), where grith is the provider client, so the prompt passes through grith on your machine. It is not uploaded there either.

Does grith contact grith.ai?

On any install: a supervisor-profile refresh from api.grith.ai, at most once every six hours, off with [general] profile_update_check = false. The version check is not one of these calls - it asks GitHub's release API, caches the answer for 24 hours, and goes away with GRITH_NO_UPDATE_CHECK or [general] update_check = false.

Signed in on a paid plan: a licence refresh roughly every 24 hours, plus analytics sync - aggregated rollups and security-event summaries every 30 seconds, and each closed UTC day as one archived file. Never commands, arguments, file paths, URLs, prompts, model responses, file contents, environment values or provider keys. Two caveats worth knowing first: project names travel in clear text, and destinations are HMACed unless an owner opts into clear labels. See Analytics.

$ grith analytics status
Cloud analytics sync
Consent:  not recorded yet — turns on automatically with a paid plan
          (or run `grith analytics enable`)
Account:  not signed in — run `grith pro login`
Plan:     requires a Pro plan
Config:   audit sync on
Device:   not registered yet
Pending:  0 day(s) awaiting upload, 0 security event(s)

Platforms and agents

Which platforms?

Linux x86_64 (kernel 4.8+) and Linux aarch64 (kernel 5.3+), as static musl binaries, so Raspberry Pi 4/5, Graviton and Ampere all work and the installer picks the right one. Anything else, macOS and Windows included, is unsupported and the installer refuses to run there. A Linux VM or container works fine.

Which agents?

Eleven profiles are compiled into the binary and grith exec picks one from the target's basename - Claude Code, Codex, Aider, Goose, Cursor, Cline, OpenClaw and Copilot, plus generic, generic-cli and grith-repl. Anything unrecognised runs under generic, which is a working profile rather than a bare one. See Built-in profiles.

Filters and tuning

Can I turn a filter off?

Yes. All 18 filters are on by default and every toggle is an off switch.

[proxy.filters.behavioural]
enabled = false

Consider raising proxy.auto_allow_threshold first - it is the narrower change. Either way the new value applies at the next daemon restart, not on the next call.

Can I write my own filter?

Not as code. What you can change is the data the filters read - the path, command, secret, egress, DLP, canary and containment rule files, and the meta-rules. See Filter config files.

Why did a call score exactly 8.0 and still get queued?

Because 8.0 queues. The thresholds are strict on both ends: allow at or below 3.0, queue above 3.0 up to and including 8.0, deny above 8.0.

Pro

What does Pro add?

Analytics history and cloud sync, the team policy editor, a concurrency ceiling of 64 supervised sessions instead of 2, and notifications, which are parked and not available yet. That is the whole list - filters, supervisor, digest, dashboard and every CLI command are in the community edition.

Is the community edition feature-limited?

Only on concurrency. Community allows 2 concurrent supervised sessions and a paid licence raises the ceiling to 64 - though a stock install still stops at 4 until you raise supervisor.max_concurrent_sessions. Both caps apply and the lower one wins.

How much is Pro, and is there a trial?

$25 per user per month, or $21 billed annually, up to 25 users - see grith.ai/pricing. The trial is 14 days and one seat, one per team and one per email.

Privacy

Where do my provider API keys live?

grith takes the first of: the provider's api_key in its [llm.*] block, the environment variable named by api_key_env (OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY), or a file under ~/.config/grith/provider-keys/ pulled by grith pro sync. Synced files are encrypted at rest with AES-256-GCM under a key derived from your account API key, so anyone holding that API key can decrypt them. See Encrypted key management.

Where does my audit log live?

~/.local/share/grith/audit/audit.db, hash-chained, with records older than the retention window archived to cold/ on the same machine. It never leaves that machine - the cloud sync that used to upload records was retired in v0.3.1, and the team dashboard shows security events and rollups instead.

Still stuck

Troubleshooting covers the failures people actually hit. After that: GitHub issues or grith.ai/contact.