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.

DefenseClaw for macOS is a menu-bar app for Apple-silicon Macs running macOS 14 or newer. It shows gateway health, alerts, inventory and sandboxes, and installs and updates the DefenseClaw runtime. It works only with the DefenseClaw installation on this Mac: the gateway API on 127.0.0.1 and the data under ~/.defenseclaw. Actions that change something run the defenseclaw CLI, and their output appears in Activity.

Install

  1. Download DefenseClawMac-<version>-macos-arm64.dmg from the release assets.
  2. Open the DMG, drag DefenseClawMac to Applications, and launch it.
  3. If DefenseClaw is not installed yet, the Set Up DefenseClaw window offers Install DefenseClaw Runtime. It downloads the matching install.sh, checks it against the release's checksums.txt, and installs the CLI and gateway into ~/.defenseclaw and ~/.local/bin. Progress shows in Activity. An existing install.sh installation is used as it is.
  4. Pick the agents to guard. Detected agents are pre-selected. Choose observe or action mode.

A release is notarized only when its Apple signing secrets were set at release time. Otherwise the app is ad-hoc signed, and macOS asks you to confirm the first launch. Update in the app installs the latest release and keeps your configuration, tokens and audit database. Running install.sh again also updates the app (see Upgrade).

Panels

GroupPanels
MonitorOverview, Alerts, Logs, Audit, Activity
GovernSkills, MCPs, Plugins, Tools, Policies, Sandboxes
DiscoverInventory, AI Discovery, Runtime, Registries
ConfigureSetup (setup forms, Sandbox wizard, config editor)

Most panels match the TUI. Settings has General, Monitoring, Notifications and Connection tabs. The menu-bar popover shows the gateway state, each connector's mode with its call and block counts, and recent events, with Open DefenseClaw, Ack All, Pause and Quit. Closing the main window keeps DefenseClaw running in the menu bar.

OpenShell sandboxes

On a Mac, sandboxes are OpenShell MicroVMs that work on a copy of your project; defenseclaw sandbox pull <name> --apply brings the changes back (see sandboxes). With sandboxes on, the app shows them in four places:

  • The menu bar lists active sandboxes, blocked destinations with Unblock, and waiting asks with Approve and Reject.
  • Notifications report a blocked destination you can unblock, an ask, a planted git repository, and hooks that cannot reach DefenseClaw. Unblock for this sandbox needs an unlocked Mac.
  • The Overview card shows counts of active sandboxes, blocked sites, asks and alerts.
  • The Sandboxes panel (⌘⇧B) lists sandboxes, their asks and the live activity feed, with stop, review, pull and undo actions.

The app never starts a harness session. It copies the defenseclaw sandbox run or connect command for you to paste into Terminal. It never installs OpenShell either; run defenseclaw sandbox setup --install-openshell in Terminal first.

The app shows the same sandboxes as the Sandboxes panel in the TUI. It reads the daemon's /api/v1/sandbox API on every refresh (every 5 seconds by default). When a refresh fails it keeps the last good snapshot and says so. The status line names the gateway's driver: (MicroVM) or (docker).

Every button, notification and wizard field is listed below. The task steps are in Watch from the TUI or app.

With sandboxes on, the popover has a Sandboxes section:

  • The number of active sandboxes (or "unavailable"); click it to open the Sandboxes panel.
  • Up to three active sandboxes with harness and uptime, orange when one has an alert.
  • Up to two blocked destinations, each with Unblock for that sandbox only.
  • Up to two waiting asks, with Approve and Reject.

Notifications

With Notify on sandbox blocked destinations and asks (with Unblock) on (Settings, Notifications; on by default), the app posts:

EventNotificationButtons
A blocked destination you can unblock"Blocked <host>": the sandbox tried to reach it, and whyUnblock for this sandbox, Review
An ask"<sandbox> asks for access" and what it wants to reachReview
A new git repository in a mounted project"<sandbox>: planted git repository"Review
Hooks that cannot reach DefenseClaw"<sandbox>: hooks are not reaching DefenseClaw"Review

Unblock for this sandbox needs an unlocked Mac and lifts the block for that one sandbox. Unblocking a host in every sandbox is a confirmed choice in the Sandboxes panel only. Review, or a click on the notification, opens the panel. Notifications name the destination and the sandbox, never request content. A destination blocked again within a minute does not notify again, and events from before the app started do not notify.

Overview card

The Overview panel shows a Sandboxes card: the status line and counts of active sandboxes, blocked sites, waiting asks and alerts, with Open Sandboxes.

Sandboxes panel

Open Sandboxes in the sidebar (Govern) or press ⌘⇧B. The sidebar item shows waiting asks. The header has the daemon's status line, your organization's policy when openshell.admin is set, Copy run command (cd <project> && defenseclaw sandbox run claude) and Refresh. When sandboxes are off the panel offers Open Setup; when unavailable, Run sandbox doctor.

PartWhat it has
SandboxesName, Phase, Harness, Pack/Profile, Mode, Up, Sites (contacted and blocked), Alerts.
Selected sandboxHarness, project, skip-permissions mode, tool calls, hook events, last tool block, undo, run image, alerts.
AsksEach waiting ask with Approve, Always… (asks first) and Reject.
ActivityThe 60 newest feed events. A blocked destination you can lift has an Unblock menu: Only in the sandbox, or In every sandbox (always)…, which asks first and adds the host to openshell.egress.unblocked. Private networks stay closed.

Actions for the selected sandbox:

ButtonRuns
Stop…Save or sync accessible work first, then defenseclaw sandbox stop <name> --yes after asking. defenseclaw sandbox connect <name> resumes it. A full-disk MicroVM with work not yet pulled keeps running and the stop exits 5, even with --yes.
Review changesdefenseclaw sandbox review <name> (sandboxes that mount their folder).
Undo…defenseclaw sandbox undo <name> --yes after asking. On a mounting sandbox it restores the pre-session snapshot. On a copy-mode sandbox it reverts the last pull --apply; later edits stay, and if one touched the same files nothing is reverted and Activity says why.
Copy connect commandCopies the resume command.
Copy pull commandCopies defenseclaw sandbox pull <name> for a review only. Add --apply to bring the work into your project, or --branch or --patch-out FILE to save it elsewhere.
Pull to branchdefenseclaw sandbox pull <name> --branch: the work lands on branch dc/<name>. A change that can run code on your Mac is not brought back this way; run defenseclaw sandbox pull <name> --apply in Terminal, where it asks.

The alerts are the same as in the TUI (see Alerts and notifications). The actions are unavailable while the installation is read-only. The app never starts a harness session; it copies the command for Terminal.

Sandbox wizard

Setup → Sandbox runs defenseclaw sandbox setup --non-interactive plus the flags your answers choose, like the TUI wizard. Fields: the action (setup, or doctor to only check), Claude Code and Codex (at least one; defaults follow openshell.harnesses), OpenShell telemetry off, Shell wrappers and Build images now. Telemetry off is the default and writes to ~/.config/openshell/gateway.env; off passes --upstream-telemetry. There is no mounts question: setup sets compute_driver = "vm" in the gateway's gateway.toml, restarts the gateway once, and every run works on a copy. The first run of each image prepares its MicroVM disk, which takes about a minute and 5 GB.

The app never installs OpenShell. When OpenShell or e2fsprogs is missing, run this in Terminal first. It installs NVIDIA's nvidia/openshell Homebrew formula and e2fsprogs and starts the gateway with brew services:

defenseclaw sandbox setup --install-openshell

On OpenShell 0.1.1 to 0.1.5, which run no new sandbox, the same command upgrades OpenShell to 0.1.6 in place, which restarts the gateway. Setup keeps the release you have while a MicroVM sandbox runs, so save or sync each guest’s work first, then stop it with defenseclaw sandbox stop NAME; a failed disk sync can lose later changes.

Config editor

Setup → Config Editor has an OpenShell Sandboxes section for the openshell: keys, with the same read-only rules as the TUI config editor. In a managed_enterprise install the whole section is read-only.