grithdocs

[supervisor]

OS-level supervisor settings — interception mechanism, default profile, noise reduction.

The [supervisor] section controls how grith exec intercepts syscalls and how noisy a session looks to the filters.

[supervisor]

KeyTypeDefaultDescription
attach_modestring"traceme"Linux attach mechanism: "traceme" (shipped) | "seize" (work in progress — selecting it currently aborts with a clear error). See work/futurework/ptrace-seize-migration.md.
authority_lost_terminate_after_secondsinteger0Seconds to keep running after the daemon stops accounting for this session (it answered a heartbeat with "I am not tracking you" — usually because it restarted while at its session cap). 0 = never terminate: the session keeps running with a loud warning and you decide. Terminating by default would destroy in-progress agent work over a daemon-side event you did not cause. Set a positive value in CI, where nobody is watching the warning.
default_profilestring"generic"-
enabledbooleantrue-
freeze_timeout_secondsinteger300-
max_concurrent_sessionsinteger4-
pty_forwardingbooleantrue-
pty_ownership_enforcebooleanfalseH2 Option 1 (IPC-delegated authority): enforce PTY ownership. When false (default), writes to a /dev/pts/N that is NOT the supervised tool's own controlling terminal are detected and forensically logged (event = "foreign_pts_write") but still allowed — audit-only, to measure the false-positive budget. Set true to DENY them (the `echo cmd > /dev/pts/<other pane>` IPC-injection vector). See work/futurework/ipc-delegated-authority-escape.md.
require_sandboxbooleanfalse-

[supervisor.platform]

KeyTypeDefaultDescription
linux_mechanismstring"ptrace"-
macos_mechanismstring"endpoint-security"-
seccomp_pre_filterbooleanfalse-

[supervisor.noise_reduction]

KeyTypeDefaultDescription
batch_rapid_readsbooleantrue-
batch_window_msinteger50-
ignore_read_onlybooleantrue-

[supervisor.dns_inspection]

KeyTypeDefaultDescription
accept_proxy_network_authoritybooleanfalseA proxy-owned upstream socket can have network access the tracee lacks due to cgroups, firewall owner rules, SO_MARK/SO_BINDTODEVICE, or policy routing. Set true only after that authority difference is explicitly reviewed and accepted or equivalently contained. The proxy refuses to start otherwise.
block_tcp_dnsbooleantrueDeny TCP-DNS, forcing resolution onto the inspected UDP path. TCP-DNS can't be content-inspected (its query/response ride write()/read(), the hottest syscalls, deliberately not intercepted), so leaving it enabled would let a tool bypass query blocking over TCP. The rare cost is a lookup whose answer exceeds EDNS0-UDP size failing (modern resolvers use EDNS0 UDP up to 4 KB, so TCP fallback is seldom needed); such a case surfaces as a visible deny. Set false to allow TCP-DNS uninspected. Default on.
connected_udp_proxybooleanfalseCanary path for connected UDP/53 sockets whose query/response use plain write()/read() and are therefore invisible to in-line inspection. Off until the Phase 0 resolver, namespace, race, lifecycle, and performance gates pass.
enabledbooleantrueIn-line DNS inspection (Linux). Discovers connected and unconnected UDP DNS destinations, parses every sendto/sendmsg/sendmmsg query before send, and lets allowed queries reach the machine's real resolver untouched. Malformed port-53 payloads fail closed. DoT (port 853) is denied.
observe_responsesbooleantrueObserve DNS responses to populate the exact IP->domain cache the egress / reputation filters use. This promotes tracked recvfrom/recvmsg/recvmmsg calls to catch their exits (one tightly-scoped PTRACE_SYSCALL step per DNS receive). Query blocking does not depend on this. Default on.
proxy_control_capacityinteger256-
proxy_max_response_bytesinteger4096Bound the proxy data plane. Oversized responses fail explicitly rather than being silently truncated.
proxy_policy_capacityinteger128-
proxy_policy_timeout_msinteger1000-
proxy_query_capacityinteger1024-
proxy_queue_actionstring"refuse"QUEUE-range policy decisions from either DNS inspection owner (the in-line sendto/sendmsg path and the connected-UDP proxy) enqueue review but refuse the current lookup. "forward" is an explicit compatibility mode which permits DNS before review and must not be used for complete-enforcement claims.
proxy_route_capacityinteger256-
proxy_shutdown_timeout_msinteger2000Bounds route-task draining; the owning thread is always joined afterward.
proxy_upstream_timeout_msinteger5000-

Notes

  • enabled — when false, grith exec falls back to a no-op pass-through (useful for testing wrapper compatibility without enforcing). Audit log still records calls.
  • default_profile — applied when --profile isn't passed to grith exec. Conservative default: generic.
  • freeze_timeout_seconds — how long a frozen process can wait for a digest decision before grith auto-denies. Should match (or be slightly less than) [proxy] review_timeout_seconds.
  • max_concurrent_sessions — soft cap on simultaneous supervised sessions. Exceeding it returns an error from grith exec rather than degrading performance.
  • pty_forwarding — required for interactive agents. Disabling breaks agent TUIs.
  • require_sandbox — when true, refuses to supervise unless the process is running inside a container or user namespace. Belt-and-braces.

Platform mechanisms

The supervisor uses different OS mechanisms per platform. v0.1 supports ptrace + seccomp on Linux x86_64; other platforms ship in v2.0. See Syscall interception for mechanism details.

Noise reduction

The most useful knobs are:

  • ignore_read_only — skip filter pipeline for read syscalls on already-open fds (the open was already scored). Default true.
  • batch_rapid_reads — coalesce rapid reads from the same fd into a single filter pass per batch_window_ms. Default 50ms window.

Both are safe to leave on. Disable only for forensic recording where you want every syscall captured raw (use --trace-syscalls-jsonl on grith exec for that).

See also

Previous[llm]Next[server]
Last updated: 2026-05-14Edit this page on GitHub →