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 tuiUse 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.

Panels

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.
| Key | Panel | What it shows |
|---|---|---|
1 | Overview | Gateway 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 |
2 | Alerts | Recent 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 |
3 | Skills | Scanned skill inventory, with block and allow actions |
4 | MCPs | Scanned MCP servers, with block and allow actions |
5 | Plugins | Installed plugins and their scan results for every connector that has plugins (Amp, Hermes, OpenClaw and others), with block and allow actions |
T | Tools | The 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) |
6 | Inventory | Combined inventory view, with sub-tabs for skills, plugins, MCPs, agents (including agent identities), tools, models, memory and IDE plugins |
7 | Sandboxes | OpenShell sandboxes, their live activity feed, and the rare asks (below) |
8 | Logs | Live gateway logs with filter presets. The view opens on the newest line and follows new lines until you move the cursor |
9 | Audit | Audit 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 |
A | Activity | Live 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) |
V | AI Discovery | Discovered AI agents, components, and local models, including model status and format |
N | Runtime | What actually ran: the runtime planes and their findings |
R | Registries | Configured registries |
P | Policies | The protection center: posture per connector, opt-in packs, chains, rule families, policies, rule packs and sandbox packs (below) |
0 | Setup | Setup 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:

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.

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) orunknown. A Remote-SSH server's IDE cell readsvscode (ssh), so a local and a server copy of the same extension look different. - AI is
yesfor 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,allowandunblockwriteasset_policy.<type>.deniedor.allowedinconfig.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 offersu, and a row with no entry offersbanda.disable,enable,quarantineandrestoreare runtime actions kept in the audit database, not inconfig.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
- Check health. On Overview, press
Dto rundefenseclaw doctorin the background. The Doctor card shows the last result. - Run a command. Press
:orCtrl+Kto search and run any command. The Risk column marks what changes things. - Block or allow an asset. On Skills, MCPs, Plugins or Tools, press
bto block,ato allow,uto unblock. Each key shows the command before it runs. - Change protection. On Policies, press
mto switch a scope between observe and action.b,a,handpset block level, alert level, human approval and rule pack. - Edit settings. On Setup, press
cfor the config editor, thenSto 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 protectedornot confirmed) and the clock time of the last Cowork event, orno Cowork event yet. While Cowork is not protected, a Cowork next row gives the missing step. These are the rowsdefenseclaw statusprints, 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 assetup cowork. - Alerts. A finding from a Cowork call shows the target
cowork:PreToolUsein the row and in the detail, and the detail has aSurface: Cowork (Claude Code)line. A Claude Code call from the terminal keepsclaudecode:PreToolUse.
Handy keys
| Key | Action |
|---|---|
? | 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+P | Jump 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 Alerts | Search 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 |
D | Run defenseclaw doctor in the background and toast the result (works on every panel) |
Y | Copy the last command's output (works on every panel) |
Ctrl+S | Save the last run to a log file |
Ctrl+C | Quit the TUI (it cancels a running command first) |
q | Close the open drawer, overlay or detail; quit when nothing is open (it never cancels a running command) |
b | On Overview and Logs: turn desktop notifications on or off |
e | On 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.

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.
| View | What it shows |
|---|---|
| Posture | One 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 packs | The 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. |
| Chains | The 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 families | The 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. |
| Policies | Every named policy with the active one marked; Enter picks one to activate. |
| Rule packs | The rule pack of each scope; Enter switches it for all connectors or one. |
| Sandbox packs | The OpenShell sandbox packs (read-only; not shown on Windows). |
On Posture, change the highlighted scope with one key:
| Key | Change | Runs |
|---|---|---|
m | Observe ↔ action | defenseclaw guardrail mode observe|action [--connector NAME] |
b | Block tool calls at CRITICAL, HIGH+ or MEDIUM+ (or back to the pack's level) | defenseclaw guardrail block-at LEVEL [--connector NAME] |
a | Alert at CRITICAL, HIGH+, MEDIUM+ or LOW+ (or the pack's level) | defenseclaw guardrail alert-at LEVEL [--connector NAME] |
h | Human approval off, or for CRITICAL, HIGH+, MEDIUM+ or LOW+ | defenseclaw guardrail hilt on|off … |
p | Rule pack | defenseclaw 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.

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:
| Key | Action |
|---|---|
Tab / Shift+Tab or ← / → | Previous or next section |
g | Pick a section from a grouped list |
/ | Find a field by name or key in any section |
Enter | Edit the field (text box) or change a choice |
S | Review the changes and save |
r | Revert unsaved changes (R opens Registries) |
w | Back 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 save | What the TUI shows | What to do |
|---|---|---|
| Only keys the gateway applies on its own | Config 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 key | Config 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 running | Config 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 --jsonOn 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.

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.
| View | Columns | What it shows |
|---|---|---|
| Sandboxes | Name, Phase, Harness, Pack/Profile, Mode, Up, Sites, Blocked, Tool calls, Alerts | Every 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. |
| Activity | Time, Sandbox, glyph, Event | The 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). |
| Asks | Sandbox, Kind, Destination, Binary, Risk, Reason | Asks 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
| Key | Action |
|---|---|
t | Switch between Sandboxes, Activity and Asks |
j/k or Up/Down | Move through the view |
Enter | Open the highlighted row's details |
u | Unblock 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 / x | Approve 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 |
c | Connect: start the sandbox if it is stopped and attach its harness |
n | New run: open the launch dialog |
s | Save 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> |
d | Delete the sandbox (asks first) with its providers, credentials and snapshot. Undo is no longer possible; your project folder keeps its current contents |
U | Save 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 |
R | Review the changed files that can run code on your machine (a sandbox that mounts its folder) |
P | Pull 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 |
w | Sandboxed by default: turn the shell wrapper on or off per harness (defenseclaw sandbox enable or defenseclaw sandbox disable) |
r | Refresh 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
.gitto.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
Hooksline 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, asdefenseclaw alertsdoes withsandbox=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.harnessesfirst and only thoseopenshell.admin.allowed_harnessesallows. - 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,balancedorstrict), 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.
| Field | Flag | Default |
|---|---|---|
| Harnesses (Claude Code, Codex, Amp, Antigravity, GitHub Copilot CLI, Cursor Agent, Devin CLI, Hermes Agent, Kiro CLI, OpenCode) | --harness <name> for each one on | The ones in openshell.harnesses, else Claude Code and Codex; only harnesses openshell.admin.allowed_harnesses allows are listed |
| Credentials | none | Names 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 machine | none | Docker, 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-openshell | On 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 off | On: 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 off | On: 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-wrappers | Off. On makes the chosen harnesses' commands (claude, codex, ...) run sandboxed when you type them |
| Build Images Now | --skip-images when off | On. 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 setting | Read-only openshell keys |
|---|---|
required_pack | pack, pack_dir |
allow_yolo: false | yolo |
allow_mount: false | workdir.mode |
allow_host_ports: false | mcp.host_ports |
allow_unblock: false | egress.allow, egress.unblocked, egress.feed |
locked entry pack | pack, pack_dir |
locked entry profile, yolo, workdir.mode, workdir.unmask, mcp.import or mcp.host_ports | The key of the same name |
locked entry resources | resources.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
- Watch from the TUI or app: the task steps for sandboxes
Redaction
Configure centralized, field-aware redaction independently for local history, buckets, and export destinations in DefenseClaw observability.
macOS app
DefenseClaw for macOS, the native menu-bar companion app. Its panels, and how the menu bar, notifications, the Overview card, the Sandboxes panel and the Sandbox wizard work with NVIDIA OpenShell sandboxes.