Terminal UI (TUI)

The DefenseClaw TUI is a full-screen, keyboard-driven dashboard over the defenseclaw CLI. It surfaces the gateway status, your scanned inventory (skills, MCPs, and plugins), alerts, logs, audit trail, OpenShell sandboxes, policies and rule packs, and setup — all in one place. Operator actions use the same supported CLI and gateway surfaces, so you do not have to memorize their syntax.

Open the TUI

defenseclaw tui

That's it. The TUI opens full-screen in your terminal. Use a reasonably large window for the best layout. Run defenseclaw init first if you haven't yet, so the panels have data to show.

Panels

Switch panels with the number/letter key shown, from any panel (only an open Setup form or the config editor types digits), or cycle with Tab / Shift+Tab. Press Ctrl+P to fuzzy-jump to any panel by name. On a narrow terminal every tab stays on screen: the most-used tabs keep their names and the rest show only their key.

The Overview panel's AI Agents metric intentionally excludes local_model rows so a large model cache cannot hide agent activity. Open AI Discovery with V for the full model inventory; model rows add Model, Model status, and Format columns, with recipe, modality, device, byte size, and pinned state in the detail view when the source reports them.

Doctor status and cache

The Overview panel reads ~/.defenseclaw/doctor_cache.json; it does not rerun credential or network probes during rendering. Doctor schema v2 keeps health checks and repair attempts in separate ledgers, and the Overview derives the run outcome from both. A failed or dependency-blocked repair therefore cannot produce an all-green Doctor card.

Unknown or malformed schema-v2 state becomes a visible warning rather than being assumed healthy. Snapshots older than 15 minutes are marked stale, and pressing D runs Doctor in the background to refresh the view. Failed credential checks also feed the bounded missing-credential notice without exposing values. See the Doctor cache reference for the on-disk format.

Policies panel (protection center)

Press P (or p on Overview) to open Policies. The header sums up your protection, for example ● default policy · default pack · 1 of 5 opt-in packs · 26 chains (4 can block). Pick a view from the list on the left (or press 1-7); the pane on the right (below the table on narrower terminals, and on i at 80x24) explains the highlighted row and what you can do with it.

On Posture, change the highlighted scope with one key:

On Opt-in packs, s changes the scope and Space (or Enter) turns the highlighted pack on or off with defenseclaw guardrail protection enable|disable NAME [--connector NAME]. Turning a pack on tells DefenseClaw that the scope works against that kind of protected resource (for example a production database), so the confirm step says so; the pack is merged into a pack of its own under ~/.defenseclaw/policies/guardrail/protected-<scope>/, checked with the rule-pack validator, and only then switched to. A global change lists connectors that keep their own pack.

Every change shows what it does first. The confirm step turns red and asks twice when protection gets weaker (for example action → observe, a higher block level, approval off, or an opt-in pack off). Mode, level, pack and opt-in changes restart a running gateway so they take effect (hook decisions read the configuration the gateway started with); a stopped gateway is never started.

In the Policies view, b and a edit the highlighted named policy's own block and alert thresholds, which apply to LLM traffic through the guardrail proxy (defenseclaw policy edit guardrail …, which reloads the gateway). Overview's Policy posture reads, for example, strict · block MEDIUM+ · alert LOW+, and the status line shows policy <name> · <mode>.

Setup panel

Press 0 for Setup. The list on the left groups the tasks by goal: Get protected, Guardrail & scanning, Alerts & telemetry and Gateway & advanced, with a count and a ! when something needs attention; on narrow terminals it becomes a one-line switcher (←/→). Each task shows its real state, such as ✓ on · observe, ! not set or ○ not set up, and the pane beside it says what the task does, what is set now, what needs attention (with the fix) and what it runs. The line above sums up readiness (for example 7 ok · 3 need attention); press i for every check and its fix command. The hint line and ? list only the keys of the view you are in.

In a task form, Enter on a text field (or just start typing, or paste) opens a text box: Enter saves the value, Esc cancels, and Ctrl+T shows a hidden secret. ←/→ or Space change a choice, and Ctrl+R runs the task. Secrets you enter for API keys & secrets reach defenseclaw keys set --value-stdin on standard input, never on the command line. Follow-up commands run only after the previous one succeeds.

Press c for the config editor. On wide terminals its sections are listed on the left, grouped (Core, Protection, …), with the highlighted field's value and help beside the table:

Keys the TUI can't save show as read-only rows; their hint says where to change them (in config.yaml, or with defenseclaw setup <connector> for connector hooks). Only problems in fields you changed block a save.

Sandboxes panel

Press 7 for Sandboxes, the TUI's view of the NVIDIA OpenShell sandboxes the DefenseClaw daemon runs (see the sandbox guide). It reads the daemon's /api/v1/sandbox API every 5 seconds while the panel is open, and every 15 seconds in the background once sandboxes are on, and it follows the daemon's live activity feed. When a refresh fails, the panel keeps the last good snapshot and says how old it is, so a daemon restart does not look like "no sandboxes". Sandboxes run on Linux, and on Apple-silicon Macs in OpenShell MicroVMs, where every run works on a copy (see macOS); on Windows the panel says sandboxes are not supported. The macOS app shows the same sandboxes in its menu bar, notifications and Sandboxes panel.

The header shows the state (READY, OFF, WAITING, UNAVAILABLE or UNREACHABLE), how many sandboxes run, how many asks wait, the gateway with its compute driver (docker, or MicroVM for OpenShell's vm driver), and your organization's policy when openshell.admin is set. OFF points to the Sandbox wizard; UNAVAILABLE gives the daemon's reason and suggests defenseclaw sandbox doctor.

Views

t cycles through three views. Enter opens the highlighted row's details; the details window takes the keys of its view, and Esc closes it.

Keys

Blocks of private networks, cloud metadata addresses and your organization's block lists cannot be lifted here. When openshell.admin.allow_unblock is false, u and A say "blocked by your organization's DefenseClaw policy" and what to do instead, and a host your openshell.egress.unblocked lists but the policy blocks again says "your saved unblock is off". The confirmations of delete, undo and the "always" choices start on Cancel. A sandbox that works on a copy has no review: P brings its work back, and U reverts the last apply. The KEYS line and the details window offer P pull in place of R review for such a sandbox.

Alerts and notifications

The Alerts column, the alert line above the table, and the details name what needs attention:

• tamper: tool calls ran without a DefenseClaw verdict.
• nested repo: a new git repository or submodule entry appeared inside the mounted project. DefenseClaw renames a new .git to .git.defenseclaw-quarantine-<time> within seconds: at once on Linux, where it watches the folder with inotify, and on its next scan (about every 5 seconds, longer for a large project) on macOS or when the file-watch limit is reached. Until the rename, git on your machine could still read the planted repository; see the sandbox guide.
• hooks unreachable: the harness's hooks cannot reach DefenseClaw, so they block every tool call. Run defenseclaw sandbox doctor.
• silent: the harness is active, but no DefenseClaw hook has been heard. In a user-tier harness the agent may have changed what runs the hooks (what it can change differs per harness; the launch banner's Hooks line says it).
• orphaned: the sandbox has no DefenseClaw binding, so its hooks cannot authenticate. Delete it and run again.

The TUI also toasts a blocked destination you can unblock (once per sandbox and host per minute), a new ask, hook tamper, hooks that stop or start reaching DefenseClaw, and a new git repository in a project. The alert line names hooks that cannot reach DefenseClaw first, then hook tamper. The Sandboxes tab badge counts the waiting asks plus the distinct destinations u could lift.

Start a run from the TUI

n opens New sandboxed run:

• Harness: every harness DefenseClaw runs, with the ones in openshell.harnesses first and only those openshell.admin.allowed_harnesses allows.
• Project folder: the only folder the agent sees. Your home folder, a folder that contains it, and top-level system folders are refused.
• Name (optional), Network profile (the pack's, open, balanced or strict), Work on a copy (--copy) and Keep the harness's own permission prompts (--safe). When the gateway runs OpenShell's MicroVM driver, which mounts no host folders, Work on a copy is ticked and locked, and the dialog says that pull (P) brings the changes back.

Ctrl+S starts and Esc cancels. When another sandbox already mounts the folder live (stopped or not; a folder takes one live mount), the TUI asks first: run this one on a copy, connect that sandbox instead, delete it first (which asks again), or cancel. The TUI then hands the terminal to defenseclaw sandbox run <command> in that folder (claude, codex, ...), exactly as on the command line: the harness owns the terminal, and after its end-of-session summary, Enter brings the TUI back. c hands the terminal to defenseclaw sandbox connect <name> the same way. While the terminal is handed over, Ctrl-C belongs to the command (at its prompts, say) and never quits the TUI; at "Press Enter to return to DefenseClaw" it returns too.

Sandbox wizard

In Setup (0), select Sandboxes (OpenShell) under Guardrail & scanning, and press Enter. The form runs defenseclaw sandbox setup --non-interactive with your answers as flags, so your answers are the consent: the command asks nothing else, and only sudo may ask for your password. Choose the action doctor to check this machine with defenseclaw sandbox doctor instead; its result is labelled sandbox doctor, and the wizard's status shows checked or check failed rather than a finished setup.

A gateway change (bind mounts, telemetry) restarts the OpenShell gateway, which drops the connections of every sandbox running on it; while sandboxes run, setup skips the restart, and defenseclaw sandbox doctor --fix applies it later. Long hints wrap in the form. The Will run line previews the command. Ctrl+R runs it: after a confirmation, the TUI hands the terminal to the command so sudo prompts and image builds show, and comes back when it ends.

Sandbox settings in the config editor

In Setup, c opens the config editor. Its OpenShell Sandboxes section edits the openshell: keys described in the configuration reference. Keys the selected policy pack governs show inherit until you set them, and defenseclaw sandbox policy explain shows every resolved setting with its source. The Organization Policy row summarizes openshell.admin; the editor never changes it, so edit config.yaml directly.

Keys an administrator constrains through openshell.admin are read-only. The row shows the value that takes effect, for example open (locked), or true → off by policy for yolo under allow_yolo: false. Its hint, which Enter or Space also shows in the status line, reads "Read-only: blocked by your organization's DefenseClaw policy" with the reason. The Profile choice offers only profiles at least as strict as admin.min_profile. In a managed_enterprise install every key of the section is read-only, because the administrator owns config.yaml.

The policy packs and admin limits page explains what each setting enforces. The macOS app's config editor applies the same rules.

Handy keys