grith exec

Supervise an external CLI tool at the syscall level - flags, session verbs, prompt keys and the daemon requirement.

grith exec [OPTIONS] -- <COMMAND> [ARGS...]
grith exec [OPTIONS] --attach <PID>

Spawn a tool under grith's syscall interception, or attach to one already running. Everything the tool touches - files, processes, sockets, D-Bus - is scored before the kernel is allowed to carry it out.

grith exec -- claude
grith exec --profile codex -- codex

The profile is picked from the program's basename unless you name one. Anything unrecognised falls back to supervisor.default_profile, which ships as generic.

Flags

Flag	What it does
`--profile <NAME>`	Use a specific built-in profile instead of auto-detection.
`--attach <PID>`	Supervise a process that is already running, instead of spawning one. No seccomp filter is installed on an attach, so every syscall costs a ptrace stop.
`--workspace-only`	Confine file access to the workspace. See below.
`--allow-queued`	In a session with no terminal, allow and log queued operations instead of denying them.
`--syscall-log <FILE>`	Write every syscall request and its decision to a file. The file is created fresh each run, so point each session at its own path.
`--trace-syscalls-jsonl <FILE>`	Write raw pre-filter forensics records as JSONL, for `grith profile audit`.

`--workspace-only` since 0.3.1

Restricts file access to the directory grith exec was launched in, its linked git worktrees, and anything in supervisor.trust.additional_project_roots. Reads and writes outside that set are denied rather than scored.

System runtime paths stay readable and the profile's routine paths still work - otherwise most tools could not start. Network and process spawning are unaffected; this fences the filesystem only.

⚠️The flag only tightens

There is no --no-workspace-only. A flag that could loosen a configured boundary would let anything able to invent an argv undo the operator's posture. To turn the boundary on permanently, set supervisor.trust.restrict_to_workspace = true in config.toml.

Full behaviour, including what stays readable and which directories can be blocked, is on The workspace boundary.

Headless sessions fail closed

With no terminal and no dashboard overlay there is nobody to answer a prompt, so a queued operation is denied immediately rather than blocking for the review timeout. --allow-queued flips that to allow-and-log. It has no effect in an interactive session, where the dialog is shown as usual.

That default is what you want in CI. See Running in CI.

Answering a prompt

When a call queues, the TUI shows a dialog:

Key	Action
`a`	Allow this request; the exact target stays allowed for this session
`d`	Block it; identical retries are blocked for a short window
`l`	Allow, and save a permanent rule for this exact target
`s`	Allow a directory for operations you pick, this session only
`b`	Block a directory for the rest of the session since 0.3.1
`t`	Deny and stop the supervised tool
`i`	Show raw arguments and the request id
`h`	Help overlay
`esc`	Deny

s and b are offered only when the score is 8.0 or below. Nothing outlives the session unless you save it with l, and sensitive targets are never saved.

Pressing Ctrl+C twice within a second force-quits and denies everything pending. The status bar advertises the rest: [shift+pgup] scroll, [ctrl+t] select text, [ctrl+l] log, [a/d] when prompted. Ctrl+T hands the mouse back to your terminal so drag-select and copy work normally, and pauses repaints while you select.

Managing sessions

Three bare verbs, which are not in --help:

grith exec list
grith exec kill <session-id>
grith exec prune

They are matched only when there is no --, no --profile and no --attach. Given grith exec -- list, list is the program you are supervising.

list prints one row per live session - short id, tool, project, pid, uptime, intercepted counts and containment state - then a capacity line. kill sends SIGTERM to the root pid. prune clears dead registry entries and reports how many are left.

Both kill and prune are also offered in the message you get when the plan's concurrent session cap is reached. The effective ceiling is the lower of the licence cap and supervisor.max_concurrent_sessions. The licence allows 2 on Community and 64 on paid plans; the config ships at 4. So Community stops at 2 whatever the config says, and a stock paid install stops at 4 until you raise the config value.

It will not start without a daemon

exec is a thin client over the local daemon and has no in-process fallback. If the daemon is missing, unauthenticated or a different version, no session starts at all.

terminal

$ grith exec list
Grith could not establish a trusted connection to the local daemon.
Found a Grith daemon on 127.0.0.1:3141 running 0.2.5, but this CLI is 0.3.1.

No supervised session was started.
Run: grith dashboard restart
Then retry the command.
Error: daemon not ready (version_mismatch) — no supervised session was started

The same refusal is logged as daemon_unready_exec_refused with a code naming the cause. grith daemon restart fixes the common ones.