Terminal UI (TUI)

The DefenseClaw terminal UI — a keyboard-driven dashboard over the defenseclaw CLI. How to open it, a tour of the panels, the config generation and policy digest it shows, block and allow actions, the Policies panel, Setup and the config editor, and the Sandboxes panel for OpenShell sandboxes.

The DefenseClaw terminal UI (TUI) is a full-screen, keyboard-driven dashboard over the defenseclaw CLI. It shows gateway status, alerts, scanned inventory, the audit trail, sandboxes, policies and setup in one place. Actions run the same CLI and gateway commands you would type, and show the command first.

Open the TUI

defenseclaw tui

Use a terminal of at least 80×24. Wider terminals show more columns and put the detail pane beside tables instead of below them. Run defenseclaw init first so the panels have data.

This page is for a DefenseClaw you installed yourself. A managed computer (an enterprise package, MDM or Setup) has no TUI and no defenseclaw init. On Linux and macOS the user's defenseclaw runs only the commands in Managed command availability, and answers tui, init and anything else with "This computer is managed; use defenseclaw status for your protection state, defenseclaw sandbox status for your sandboxes and defenseclaw sandbox policy explain for your policy." followed, on Linux and macOS, by the administrator views of that computer (the installed gateway's enterprise linux status or enterprise macos status, verify and audit export --since 2h) and exit 2. On Windows the managed defenseclaw.exe is the administrator CLI. An administrator checks a managed computer as shown in On a managed device.

At 80×24, Overview notices wrap to show the full action; use the arrow keys to scroll when they extend beyond the screen. In Inventory → Summary, use j/k, arrow keys, Page Up/Page Down or End to reach lower metrics such as Agents.

DefenseClaw TUI Overview panel at 120×36: the tab bar, hook call, block, finding and guardrail cards, the connector scope, services and enforcement summaries, and the Restart Gateway, Run Doctor and Scan AI Agents buttons

Panels

DefenseClaw TUI Overview panel: the tab bar, hook call, block, finding and guardrail cards, the connector scope, services and enforcement summaries, and the Restart Gateway, Run Doctor and Scan AI Agents buttons

On Overview, press G to start or restart the gateway and z to enable or run AI Discovery. The quick-action row at the end of Overview lists both as [G] Gateway and [z] AI Discovery (at 80x24, scroll down to it). The hint line above the status line is not a key list on Overview: it shows the most urgent notice, for example 500 recent critical/high alert events need review. Press 2 for Alerts., and a rotating tip when there is none; press ? for every key. Under 32 rows the Overview cards are four rows tall and the title shares a row with the tagline, so the services and enforcement summaries are on the first screen at 80x24.

Switch panels with the number/letter key shown, from any panel (only an open Setup form or a / search box types digits and letters), or cycle with Tab / Shift+Tab. The one exception is Sandboxes: there P, R and A are the panel's own pull, review and always-approve keys. On Sandboxes, press p for Policies, and Tab or Ctrl+P to reach Registries or Activity. Press Ctrl+P to fuzzy-jump to any panel by name. At 80 columns, the tab strip keeps every panel's key on screen and spells out the current panel (for example, 1 Overview); other tabs may show only their keys. The title below the strip names the current panel. Wider terminals add short or full names to other tabs as room allows. Unread counts stay visible on Alerts and, when space allows, on Logs and Activity; switching panels can change which other tabs have names. Below 80 columns the current panel may shorten to an ellipsis, and the panel title remains the full name.

With two or more connectors set up, m filters Overview, Alerts, Audit, Logs, Skills, MCPs, Plugins, Tools and Inventory by connector. With one connector, m on Overview switches the active connector (it re-runs that connector's setup after a confirm), and on Alerts, Audit and Logs it says there is nothing to filter.

KeyPanelWhat it shows
1OverviewGateway status, the active connector roster (every wired connector on a multi-connector install), the active policy and its posture, the applied config generation and policy digest, at-a-glance health
2AlertsRecent guardrail and hook alerts. A rule that matched a call it could not decide (a detection-only finding) is not an alert: the panel says how many the last 24 hours had, as defenseclaw alerts does, and defenseclaw audit export --since 24h lists them. The details of an alert raised in an OpenShell sandbox name it in a Sandbox fact
3SkillsScanned skill inventory, with block and allow actions
4MCPsScanned MCP servers, with block and allow actions
5PluginsInstalled plugins and their scan results for every connector that has plugins (Amp, Hermes, OpenClaw and others), with block and allow actions
TToolsThe tool block/allow list, which is asset_policy.tool in config.yaml (capital T; lowercase t is a panel key). To add the first rule, press : and type tool block <tool-name> --connector <connector> (or tool allow)
6InventoryCombined inventory view, with sub-tabs for skills, plugins, MCPs, agents (including agent identities), tools, models, memory and IDE plugins
7SandboxesOpenShell sandboxes, their live activity feed, and the rare asks (below)
8LogsLive gateway logs with filter presets. The view opens on the newest line and follows new lines until you move the cursor
9AuditAudit trail. The Blocks filter chip (move between chips with h and l; 3 still opens Skills) lists the calls DefenseClaw blocked, hook and guardrail blocks included, from the whole trail; the other views load the newest 500 events (the header says since when; use defenseclaw audit export for older ones). A row's detail names the connector, decision, mode and rule. e writes the rows of the current view to a new defenseclaw-audit-export-<date>-<time>.json in the data directory; an earlier export is never replaced
AActivityLive output from commands you run; l (Mutations; h goes back to Commands) lists config and policy changes with what changed (for example /.env/NAME: unset -> set)
VAI DiscoveryDiscovered AI agents, components, and local models, including model status and format
NRuntimeWhat actually ran: the runtime planes and their findings
RRegistriesConfigured registries
PPoliciesThe protection center: posture per connector, opt-in packs, chains, rule families, policies, rule packs and sandbox packs (below)
0SetupSetup tasks grouped by goal, and the config editor (below)

The Alerts panel counts the detection-only findings of the last 24 hours under its summary line. With an alert selected, its details name the OpenShell sandbox that raised it in the Sandbox fact:

DefenseClaw TUI Alerts panel on Linux: the summary line, a line saying 16 detection-only findings of the last 24 hours are not listed, the alert table with a paste-site block selected, and its details with the Sandbox fact myapp-claude

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.

What AI discovery finds inside an OpenShell sandbox is listed there too, as its own rows tagged Product (sandbox NAME): the same product on your machine and in a sandbox are separate rows, and the detail names the sandbox. defenseclaw agent usage --sandbox NAME lists one sandbox's.

DefenseClaw TUI AI Discovery panel with a row for Claude Code on the host and a separate row, Claude Code (sandbox myapp-claude), for what the scan found inside the sandbox

The Runtime panel reads the same gateway as agent discovery runtime status. WATCHING means every selected plane is running, with a coverage note (for example, without elevation shadow egress sees only your own connections). DEGRADED means a selected plane is unavailable or not running. It has no Tetragon lines. Only a managed Linux gateway reports Tetragon, and the managed Linux packages ship no TUI (Managed command availability). On managed Linux, sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux discovery prints the kernel sensor, the kernel controls and your own Tetragon policies, enterprise linux tetragon status the rest, and /opt/defenseclaw/bin/defenseclaw-gateway status ends its Subsystems list with a Kernel sensor: line; see Tetragon on a Linux fleet.

IDE plugins

On Inventory (6), move to the IDE plugins sub-tab with l or Right (h or Left goes back). It lists every IDE extension and plugin the gateway's last full scan found, one row each: IDE, Plugin, Version, Enabled and AI. When more than one user is present a User column comes first.

  • Enabled is yes, no, client side (a remote IDE server, whose client keeps that state) or unknown. A Remote-SSH server's IDE cell reads vscode (ssh), so a local and a server copy of the same extension look different.
  • AI is yes for plugins the signature catalog flags as AI.
  • At 80 columns the Enabled and AI columns stay whole and the wider text columns shrink.

Press Enter for the detail card: Enabled, AI, IDE, Version, User, Name, Publisher, where the enabled state came from, the scope, the matched AI signature, and the installed and last-seen times. At 80x24 the card shows its first lines only; scroll it with PageUp and PageDown. The periodic refresh keeps the open card and your cursor.

The list matches defenseclaw agent ide-plugins; see IDE plugin inventory. When AI discovery is off, or ai_discovery.ide_inventory is off, the tab says so instead of showing an empty list.

The Plugins, Agents and MCPs sub-tabs add a User column too when more than one user is present. Agents lists the agent identities (agt-) that defenseclaw agent identities shows, up to the 1,000 most recently seen. A + after its count means there are more; the command lists them all.

Doctor status and cache

The Overview panel's Doctor card shows the result of the last defenseclaw doctor run, saved in ~/.defenseclaw/doctor_cache.json; drawing the panel does not rerun credential or network checks. A failed repair keeps the card from turning all green, and a result DefenseClaw cannot read shows as a warning rather than as healthy. A result older than 15 minutes is marked stale: press D (or d on Overview) to run Doctor in the background and refresh it. Failed credential checks also feed the missing-credential notice, without showing any values. See the Doctor cache reference for the file format.

Config generation and policy digest

The status line at the bottom of every panel shows the applied config generation and policy digest as its own segment, right after the gateway:

Ready.  │  ● Gateway (up 2m)  │  ● gen 10 · 8b19ede82344  │  ● Watchdog  │  ● Guardrail (action)  │ …

The active policy and mode are a separate segment further along the line, for example ● policy strict · action (● guardrail off with the guardrail off); a narrow terminal cuts the end of the line to …, so that segment may not show at 80 columns. gen is the applied config generation counter from config.generation.json, reported as policy.config_generation by the gateway. It survives a gateway restart; when the counter is unknown or zero, the footer shows only the digest. The hex is the first 12 characters of the effective policy digest, a SHA-256 over the configuration and the policy assets it names. Compare the pair with policy.config_generation and policy.effective_digest in defenseclaw status --json. The Policy line in plain defenseclaw status shows the same policy.config_generation as config generation N. The raw policy.generation field is a separate gateway-local counter that restarts at 1; defenseclaw-gateway policy digest computes the digest from disk.

A save through the TUI or CLI config writer moves the counter once the gateway has applied it. On a per-user install, an applied hand edit also moves the counter: the gateway records the next config generation with actor hand-edit:<user>. When the gateway rejects a change it keeps enforcing the previous policy, so the footer stays where it was; run defenseclaw doctor, whose Policy row names the reason. The status line is cut from the right on a narrow terminal. See Policy generation and digest for the command output.

Block and allow from the panels

On Skills (3), MCPs (4), Plugins (5) and Tools (T), the highlighted row takes b to block, a to allow and u to unblock; o opens the full action menu (scan, info, disable, enable, quarantine, restore and so on). Each key shows the command first and then runs the CLI, for example defenseclaw skill block NAME, defenseclaw mcp allow NAME or defenseclaw tool block NAME --connector codex. With a connector filter on (m), the row's actions carry --connector so they write that connector's entry rather than a global one.

  • block, allow and unblock write asset_policy.<type>.denied or .allowed in config.yaml (Tools: asset_policy.tool) through the config writer. The gateway applies the change on its own, with no restart, and the row's Status changes on the next refresh. The action menu offers the verbs that fit the row: a blocked row offers u, and a row with no entry offers b and a.
  • disable, enable, quarantine and restore are runtime actions kept in the audit database, not in config.yaml.
  • On a managed standalone device the three policy verbs fail with the message This device is managed: the asset_policy block and allow lists are set in the admin config (MDM or management plane), which the TUI shows in the status line and in Activity. Nothing changes. See Admission reference.

Five actions you will use most

  1. Check health. On Overview, press D to run defenseclaw doctor in the background. The Doctor card shows the last result.
  2. Run a command. Press : or Ctrl+K to search and run any command. The Risk column marks what changes things.
  3. Block or allow an asset. On Skills, MCPs, Plugins or Tools, press b to block, a to allow, u to unblock. Each key shows the command before it runs.
  4. Change protection. On Policies, press m to switch a scope between observe and action. b, a, h and p set block level, alert level, human approval and rule pack.
  5. Edit settings. On Setup, press c for the config editor, then S to review and save.

? opens the help overlay for the panel you are on. q closes an open drawer, overlay or detail, and quits when nothing is open. Ctrl+C quits from anywhere.

With two or more connectors, m filters most panels by connector.

Claude Cowork in the TUI

Claude Cowork has no panel. It is a surface of the Claude Code connector, and the TUI shows it in three places.

  • Overview. Under Configuration, a Cowork row gives the state (protected, not protected yet, not protected or not confirmed) and the clock time of the last Cowork event, or no Cowork event yet. While Cowork is not protected, a Cowork next row gives the missing step. These are the rows defenseclaw status prints, so they show only on a per-user install where Claude Desktop is present or a plugin was built. With the Claude Code connector selected (m), the view shows the same rows, or, where there are none, how many Cowork events the gateway has seen since it started. A Cowork call counts as Claude Code traffic, so a Cowork-only user does not get the "0 hook events" note.
  • Setup. In the Protect an agent task, under Get protected, the Protect Claude Cowork goal runs defenseclaw setup cowork --yes. It builds the plugin zip and sets up the Claude Code connector if it is off. It does not open Claude Desktop and does not wait, so upload the zip as described in Claude Cowork. The command palette has the same command as setup cowork.
  • Alerts. A finding from a Cowork call shows the target cowork:PreToolUse in the row and in the detail, and the detail has a Surface: Cowork (Claude Code) line. A Claude Code call from the terminal keeps claudecode:PreToolUse.

Handy keys

KeyAction
?Toggle the help overlay (scroll it with j/k or PgUp/PgDn)
Ctrl+K or :Open the command palette (search-and-run any command; the Risk column marks what changes things)
Ctrl+PJump to a panel by name
/On Skills, MCPs, Plugins and Runtime: filter the list (Enter, Esc or Down returns to it; Esc on the list clears the filter)
/ on AlertsSearch the alerts: the text matches every column the table shows, including the rule id and title in Details (Enter applies, Esc clears)
Ctrl+\Theme picker
DRun defenseclaw doctor in the background and toast the result (works on every panel)
YCopy the last command's output (works on every panel)
Ctrl+SSave the last run to a log file
Ctrl+CQuit the TUI (it cancels a running command first)
qClose the open drawer, overlay or detail; quit when nothing is open (it never cancels a running command)
bOn Overview and Logs: turn desktop notifications on or off
eOn Registries: require (or stop requiring) registry approval for the selected entry's type. Registry actions (sync, approve, reject, require) keep the Registries panel in front and report the result in the status bar; their full output is in Activity

Policies panel (protection center)

Press P (or p on Overview) to open Policies.

DefenseClaw TUI Policies panel on the Posture view: the views list on the left, the posture table with the global scope and the claudecode and codex connectors, and the detail pane with the CRITICAL, HIGH, MEDIUM and LOW actions

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 ←/→ or [/]); 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.

ViewWhat it shows
PostureOne row for the global setting and one per active connector: mode (observe logs, action enforces), the levels tool calls are blocked and alerted at, human approval, rule pack and opt-in packs. The detail pane says in plain words what that scope does and shows the CRITICAL / HIGH / MEDIUM / LOW → action table.
Opt-in packsThe high-assurance deterministic packs: privacy, cloud production, database destruction, infrastructure destruction and Kubernetes production (and the staged SSH authorized-keys contract, which can't be turned on yet), with what each covers and whether it is on for the selected scope.
ChainsThe 26 built-in bounded tool-call chains (for example SQL xp_cmdshell enable → invoke, Kubernetes manifest write → apply → pod exec, download → execute), grouped by SQL, Kubernetes, cloud, host, credentials, data egress, network and security controls. ✓ marks the chains that can block; ◐ marks alert-only ones. Read-only.
Rule familiesThe rule families in the scope's pack (command, sensitive path, secret, trust exploit, C2, enterprise data, cognitive file) with how many rules each has and what it catches.
PoliciesEvery named policy with the active one marked; Enter picks one to activate.
Rule packsThe rule pack of each scope; Enter switches it for all connectors or one.
Sandbox packsThe OpenShell sandbox packs (read-only; not shown on Windows).

On Posture, change the highlighted scope with one key:

KeyChangeRuns
mObserve ↔ actiondefenseclaw guardrail mode observe|action [--connector NAME]
bBlock tool calls at CRITICAL, HIGH+ or MEDIUM+ (or back to the pack's level)defenseclaw guardrail block-at LEVEL [--connector NAME]
aAlert at CRITICAL, HIGH+, MEDIUM+ or LOW+ (or the pack's level)defenseclaw guardrail alert-at LEVEL [--connector NAME]
hHuman approval off, or for CRITICAL, HIGH+, MEDIUM+ or LOW+defenseclaw guardrail hilt on|off …
pRule packdefenseclaw guardrail use-pack PACK [--connector NAME]

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 command adds the pack's name to the scope's guardrail.rules.protections in config.yaml; the gateway layers it onto the scope's rule pack in memory when it applies the change, so no pack folder is written. A global change applies to every connector.

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). Each change is written to config.yaml through the config writer, and the running gateway applies mode, level, pack and opt-in changes on its own; a stopped gateway is never started. The gateway restarts only for a change that has to reach the installed hooks, such as a mode change that flips a connector's hook fail mode, or human approval (h). The status line's generation goes up once the gateway has applied the change.

In the Policies view, b and a change the highlighted policy's block and alert thresholds. For the active policy that is the live global level (guardrail.block_at / alert_at, the same as defenseclaw guardrail block-at); for any other policy it saves the preset until you activate it (defenseclaw policy edit guardrail … -p NAME). Pressing Enter on a policy activates it, which copies its admission actions, levels and Cisco trust level into config.yaml. Overview's Policy posture reads, for example, strict · block MEDIUM+ · alert LOW+, and the status line shows policy <name> · <mode> followed by the generation and digest.

Setup panel

Press 0 for Setup.

DefenseClaw TUI Setup panel: the readiness line, the goal groups on the left, the Get protected tasks with their status, and the pane that explains the Protect an agent task

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 the highlighted task's details, including its checks and any 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 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.

A successful run's result card hides itself after 8 seconds (its footer says so) and leaves the result on the status line; q or Dismiss clears it sooner. A failed run's card stays until you dismiss it.

The config editor

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

KeyAction
Tab / Shift+Tab or ← / →Previous or next section
gPick a section from a grouped list
/Find a field by name or key in any section
EnterEdit the field (text box) or change a choice
SReview the changes and save
rRevert unsaved changes (R opens Registries)
wBack to the task list

The Admission Defaults section has one row, Allow List Bypass (admission.defaults.allow_list_bypass_scan). On, the default, a first-party allow-list entry installs without a scan; off, it is scanned. An unset key shows true, the value it inherits.

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. If config.yaml changes on disk while you edit, the editor says Configuration refreshed from disk.: unsaved fields are preserved, save merges the fields you edited, and r reloads the file.

Saving goes through the config writer

S opens Review Config Changes, which lists each changed key with its value before and after. Confirming writes config.yaml through the same config writer as defenseclaw config set: one file lock shared with the CLI and the gateway, the whole result checked before it is written, and a new entry in config.generation.json whose actor is tui:<user>. A value that fails the check is not written, and the editor shows Config save failed: <reason>. The dialog's button reads Save, and Save and queue restart only when a key you changed needs a restart; the restart banner appears for the same keys.

What happens next depends on the keys you changed. The editor asks the writer which of them a running gateway can only apply after a restart (the restart-required keys, such as a port, guardrail.enabled or a hook fail mode):

After you saveWhat the TUI showsWhat to do
Only keys the gateway applies on its ownConfig changes saved; the gateway applies them without a restart. and, above the table, Saved 18:21 UTC.Nothing. The status line's generation goes up when the gateway has applied it.
A restart-required keyConfig changes saved. Restart the gateway (G) to apply them., an amber Saved 18:22 UTC · Restart the gateway (G) to apply it banner, and G restart gateway in the hint line.Press G. It runs defenseclaw-gateway restart, and the banner clears once the gateway has restarted. Until then the gateway keeps the old value of that key and applies the rest.
The gateway is not runningConfig changes saved; they apply when the gateway starts.Start it.

On a managed device

Managed packages ship no TUI. On Linux and macOS the user's defenseclaw launcher offers only the commands in Managed command availability; defenseclaw tui exits 2. Windows ships the native administrator CLI. Check the deployment with the packaged binary:

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --json

On Windows, run & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows status --json from an elevated PowerShell prompt. Change the administrator config through the managed lifecycle. If a separately installed Python TUI reads a managed config, its writer refuses local saves with exit 3; this does not make the TUI available in managed packages.

Sandboxes panel

The task-by-task summary is in Watch from the TUI or app.

Press 7 for Sandboxes, the TUI's view of the NVIDIA OpenShell sandboxes the DefenseClaw daemon runs (see sandboxes). 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 sandboxes on 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.

DefenseClaw TUI on Windows with the Sandboxes tab open: the panel says OpenShell sandboxes run on Linux and macOS only and that Windows and WSL2 are not supported

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.

ViewColumnsWhat it shows
SandboxesName, Phase, Harness, Pack/Profile, Mode, Up, Sites, Blocked, Tool calls, AlertsEvery sandbox, running ones first. Blocked counts blocked destinations; Tool calls reads 57 (1 blocked). The details add the verdicts per hook event under the harness's own event names (Hook events PreToolUse 12 · PostToolUse 11 · Stop 2), as defenseclaw sandbox status <name> shows them. Above the table: the newest blocked destination of the last 15 minutes that is still in force (an unblock or an approved ask for the host clears it), and the most urgent alert. Under 100 columns the table drops Pack/Profile, Mode and Up (the details show them) and the button bar gives way to the rows; the KEYS line names the keys.
ActivityTime, Sandbox, glyph, EventThe live feed, newest first (the last 500 events): ✓ an allowed destination, ✗ a blocked destination, ⊘ a blocked tool call, ↺ a lifted block, ⚠ a large upload or a finding, ? an ask, · a lifecycle step (such as creating, ready or stopped), an answered ask, a copy upload, a pull or an undo, … events skipped because the TUI fell behind. Blocks say why in plain words (webhook catcher, no OpenShell rule allows it); a tool block names the DefenseClaw rule, without the advice DefenseClaw gives the agent. A block you can lift ends in (u unblocks), one that was lifted in (unblocked) or (approved).
AsksSandbox, Kind, Destination, Binary, Risk, ReasonAsks waiting for you. An ask appears when a program in a sandbox connects around DefenseClaw's egress proxy and OpenShell drafts a rule that DefenseClaw does not decide on its own: a private-network address with every pack (unless your organization's policy refuses it), a host off the allowlist with balanced, every new destination with strict, and requests OpenShell's policy advisor flags. A port on this machine asks only if the run named it with --host-port PORT; approve that ask to open the port. Under 100 columns the table drops Kind and keeps only what the reason adds to the destination (private network).

Keys

KeyAction
tSwitch between Sandboxes, Activity and Asks
j/k or Up/DownMove through the view
EnterOpen the highlighted row's details
uUnblock a blocked destination: in Activity the selected one, elsewhere the newest one of the selected sandbox. The dialog says why DefenseClaw blocked it. Choose Only in the sandbox (until it is deleted) or In every sandbox (always), which asks again and adds the host to openshell.egress.unblocked. Tool blocks (⊘) come from DefenseClaw's guardrail rules, so u does not apply to them
a / A / xApprove the selected ask once, always approve it (asks again; every future sandbox may reach it too, and a toast confirms what was saved), or reject it. An approval applies when the agent is idle. A is not offered for a port on this machine, a private or IP-literal address, or a proposal with allowed IPs: those open for one sandbox only. Outside Asks, a switches to Asks when one waits
cConnect: start the sandbox if it is stopped and attach its harness
nNew run: open the launch dialog
sSave or sync accessible work first, then stop the sandbox (asks first; if a MicroVM's disk could not be synced first, defenseclaw sandbox stop asks in this terminal whether to stop it anyway, losing what it wrote since its last sync, the same as defenseclaw sandbox stop NAME --discard-unsynced; a no keeps it running); it is kept, so c resumes it. defenseclaw sandbox stop <name> runs in this terminal and asks again while a detached run is still going; DefenseClaw marks that run interrupted and keeps its log for defenseclaw sandbox logs <name>
dDelete the sandbox (asks first) with its providers, credentials and snapshot. Undo is no longer possible; your project folder keeps its current contents
USave work you want to keep first, then undo: preview the changes, ask, stop a running sandbox, and put the project folder back to its pre-session snapshot. For a sandbox that works on a copy, U reverts its last pull --apply instead: defenseclaw sandbox undo <name> previews the revert in this terminal and asks, and edits you made since stay
RReview the changed files that can run code on your machine (a sandbox that mounts its folder)
PPull the work of a sandbox that works on a copy: Show what comes back (defenseclaw sandbox pull <name>, which changes nothing), Apply it to the project folder (--apply, a 3-way merge that U reverts) or Put it on branch dc/<name> (--branch, which leaves your working tree alone). The command runs in this terminal: it shows the changes first and asks before it brings back a change that can run code on your machine. p still opens Policies
wSandboxed by default: turn the shell wrapper on or off per harness (defenseclaw sandbox enable or defenseclaw sandbox disable)
rRefresh now

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 sandboxes.
  • 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.
  • N alerts: the alerts raised in the sandbox since it was created, such as a rule's finding on one of its tool calls or a shadow AI destination. The details count them by severity (Alerts 2 (1 CRITICAL, 1 LOW)); in Alerts (2), / and the sandbox name list them, as defenseclaw alerts does with sandbox=NAME.

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.

FieldFlagDefault
Harnesses (Claude Code, Codex, Amp, Antigravity, GitHub Copilot CLI, Cursor Agent, Devin CLI, Hermes Agent, Kiro CLI, OpenCode)--harness <name> for each one onThe ones in openshell.harnesses, else Claude Code and Codex; only harnesses openshell.admin.allowed_harnesses allows are listed
CredentialsnoneNames the model key defenseclaw sandbox run would share with each harness, never its value. It follows openshell.llm, as a run without --llm does. Under auto (the default) that is ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN for Claude Code, and OPENAI_API_KEY, CODEX_API_KEY or the API key a codex login --with-api-key stored in auth.json (in $CODEX_HOME, else ~/.codex) for Codex; each list ends with AWS_BEARER_TOKEN_BEDROCK for Amazon Bedrock. A ChatGPT login is not shared, so it is not counted. With none nothing is shared; with a provider only its key counts, and without it runs are refused
This machinenoneDocker, Landlock, OpenShell and bind-mount status, one per line, from a sandbox doctor check that runs when the form opens. When the gateway runs (or is set to run) OpenShell's MicroVM driver, Landlock reads Landlock (MicroVM), and the MicroVM driver's own check (e2fsprogs, the driver's signature) takes the place of the bind-mount line
Install OpenShell--install-openshellOn when OpenShell is missing, its gateway needs attention, or the MicroVM driver's check fails: NVIDIA's pinned, SHA-256-verified installer, which uses sudo on Linux and installs the nvidia/openshell Homebrew formula on macOS. On macOS it also lets setup install e2fsprogs, which the MicroVM driver needs. Off on OpenShell 0.1.1 to 0.1.5, whose hint offers the upgrade: on, setup upgrades it to 0.1.6 in place, which restarts the OpenShell gateway (on a Mac only once no MicroVM sandbox runs)
Mount Project Folder--no-mounts when offOn: enables bind mounts on your local OpenShell gateway, and DefenseClaw mounts only the folder you launch from and the read-only settings Claude Code and Codex sandboxes need. Off: no Claude Code or Codex sandbox can start, and other harnesses run on a copy. Turning bind mounts on restarts the OpenShell gateway (see below). Not shown on macOS: setup runs sandboxes there in OpenShell MicroVMs, which mount no host folders, and the form says so under MicroVMs
OpenShell Telemetry Off--upstream-telemetry when offOn: setup turns OpenShell's anonymous usage telemetry off in gateway.env (on macOS ~/.config/openshell/gateway.env, which the Homebrew service reads). Changing it restarts the OpenShell gateway (see below). Not shown for a Mac gateway that no Homebrew service runs: that gateway takes the setting from the environment it was started with
Shell Wrappers--wrappers or --no-wrappersOff. On makes the chosen harnesses' commands (claude, codex, ...) run sandboxed when you type them
Build Images Now--skip-images when offOn. The first build downloads about 3 GB; off leaves it to the first run

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.

openshell.admin settingRead-only openshell keys
required_packpack, pack_dir
allow_yolo: falseyolo
allow_mount: falseworkdir.mode
allow_host_ports: falsemcp.host_ports
allow_unblock: falseegress.allow, egress.unblocked, egress.feed
locked entry packpack, pack_dir
locked entry profile, yolo, workdir.mode, workdir.unmask, mcp.import or mcp.host_portsThe key of the same name
locked entry resourcesresources.cpu, resources.memory

The sandbox policy reference page explains what each setting enforces. The macOS app's config editor applies the same rules.

See also