Operator TUI

The operator TUI (latchgate tui) is the primary interface for setting up, monitoring, and managing a LatchGate instance. It provides a full-screen terminal with six screens covering the complete operator workflow: project initialization, configuration, approvals, audit inspection, action management, allowlist editing, and policy grants.

For day-to-day operation, the TUI replaces the need to memorize individual CLI commands. Start the gate, launch the TUI, and stay there.

latchgate up          # terminal 1: start the gate
latchgate tui         # terminal 2: manage everything

Typical workflow

First-time setup — open the TUI after latchgate up, switch to the Setup screen (6), and run the init wizard (i) to choose a preset. Add operators (2 sub-tab), then principals (3 sub-tab) and grant them actions with g. Configure webhooks and secrets as needed. Run doctor (d) to verify everything. Start the gate (u).

Day-to-day operation — the Dashboard (1) shows health, pending approvals, posture status, and recent activity at a glance. When an agent triggers a gated action, the Approvals screen (2) shows it with a countdown timer — approve (a), learn+approve (l), or deny (d) with one keypress. The Audit screen (4) provides a live, filterable event log. Use Shift+R for emergency revoke if needed.

Managing the gate — edit action manifests on the Actions screen (3), manage learned domains and paths on the Allowlists screen (5), and configure operators, principals, webhooks, and secrets on the Setup screen (6).

Starting the TUI

latchgate tui

The TUI requires operator authentication (same resolution as other operator commands). For single-operator setups, credentials are auto-discovered from latchgate.toml + .latchgate/<name>.pem. When multiple operators are configured, pass --operator-key and --operator-private-key explicitly.

The TUI connects to a running gate — it does not start one. If the gate is unreachable, the TUI exits with a diagnostic message. Start the gate first with latchgate up or latchgate serve. (The Setup screen can also launch latchgate up from within the TUI once connected.)

Not compatible with --json.

Requirements

A terminal with raw mode support (any modern terminal emulator). Minimum size: 80 columns × 24 rows. Below that threshold the TUI displays a size warning instead of rendering screens.

Built on ratatui with crossterm as the backend.

Screens

The TUI has six screens, accessible by number key (1–6) or by cycling with Tab/Shift+Tab.

Key	Screen	Purpose
1	Dashboard	Gate health, pending approvals, posture breakdown, recent activity
2	Approvals	Real-time approval queue with approve / learn+approve / deny
3	Actions	Browse, edit, and create action manifests; build custom presets
4	Audit	Paginated, filterable audit event log
5	Allowlists	Manage learned egress domains and path globs per action
6	Setup	Config viewer, doctor checks, operator/principal/policy/webhook/secret management, init wizard, gate lifecycle

Dashboard (1)

The default screen. A compact health bar at the top shows gate status, uptime, registered actions, pending approvals, dependency health (Redis, OPA), and security posture. When any security protection is relaxed, a posture breakdown line shows which protections are affected. Below the health bar, a recent-activity feed shows the latest audit events.

Key	Action
Enter	Jump to Approvals screen
r	Force refresh

Approvals (2)

Real-time approval management. Pending approvals appear with countdown timers showing time remaining before expiry. A badge count on the tab label (e.g. Approvals(3)) indicates pending items from any screen.

Key	Action
a	Approve selected (prompts for confirmation)
l	Learn domain/path + approve (prompts for confirmation)
d	Deny (opens reason input)
↑/k	Move cursor up
↓/j	Move cursor down
Enter	Jump to Dashboard (when queue is empty)

The l (learn+approve) key is context-sensitive: it appears in the status bar only when the selected approval has unresolved domains or paths. The learned entry is persisted only if execution succeeds — same semantics as latchgate approvals approve --learn-domain on the CLI.

Actions (3)

Browse the action registry, edit manifests on disk, create new actions, and build custom presets.

List mode (default):

Key	Action
↑/k	Move cursor up
↓/j	Move cursor down
e	Edit selected action manifest
n	Create new action
p	Build custom preset
r	Refresh action list

Edit mode (after pressing e):

Key	Action
↑/k	Previous field / list item
↓/j	Next field / list item
Enter	Edit field / cycle risk level
a	Add item (list fields)
d	Delete item (list fields)
s	Save changes to disk
Esc	Discard and close editor

Preset builder (after pressing p):

Key	Action
↑/k	Previous item
↓/j	Next item
Space	Toggle action selection
Enter	Proceed to next step
Esc	Cancel

Create wizard (after pressing n):

Key	Action
↑/k	Previous option
↓/j	Next option
Enter	Confirm selection
Esc	Cancel

Audit (4)

Paginated audit event log with filtering and text search. Events stream in during each tick cycle and can be browsed backward.

Key	Action
f	Cycle filter (decision → action → principal → event_type)
/	Text search across visible fields
o	Load older events (backward pagination)
r	Clear and refetch
↑/k	Scroll up
↓/j	Scroll down
Home	Jump to newest
End	Jump to oldest

Allowlists (5)

Manage learned egress domains and path globs per action. A sub-tab header toggles between Domains and Paths — both share the same interaction model. Entries are scoped per action: a domain learned for slack_post is not available to web_read.

Equivalent to the latchgate domains CLI commands (for the Domains sub-tab) and the /v1/admin/paths admin API endpoints (for the Paths sub-tab), but with a live, interactive interface.

Key	Action
d	Switch to Domains sub-tab
p	Switch to Paths sub-tab
←/h	Previous action
→/l	Next action
/	Filter actions by name
↑/k	Move cursor up
↓/j	Move cursor down
a	Add domain or path glob
x	Remove selected entry
c	Clear all entries for action

Setup (6)

Configuration and management hub with six sub-tabs. Sub-tabs are navigated with ←/→ (or H/L) and 1–6.

Sub-tab	Key	Contents
Overview	1	Config summary, doctor checks, gate lifecycle
Operators	2	Operator credentials (add/remove)
Principals	3	Peercred identity mappings + policy ACL (grant/revoke)
Webhooks	4	Webhook endpoints (add/remove/test)
Secrets	5	SOPS-encrypted secrets (init/set/remove)
Presets	6	Browse built-in presets, build custom presets

Overview sub-tab:

Key	Action
i	Run init wizard (suspends TUI, launches interactive wizard, returns)
u	Start gate via latchgate up (suspends TUI for startup output)
s	Set a config value (opens key/value input)
d	Run doctor checks
e	Open latchgate.toml in $EDITOR (suspends TUI, resumes on exit)

Operators / Webhooks sub-tabs:

Key	Action
a	Add item (opens form input)
r	Remove selected item
↑/↓	Navigate list

Principals sub-tab:

Two-panel layout: the left panel lists peercred identity mappings (UID, name, scopes), the right panel shows the policy ACL grants for the selected principal — including any wildcard (*) grants that apply to all callers.

Key	Action
a	Add peercred principal (UID/name/scopes)
r	Remove selected peercred principal
g	Grant action to selected principal (policy)
x	Revoke action from selected principal
↑/↓	Navigate list

Secrets sub-tab:

Key	Action
i	Initialize SOPS encryption
s	Set a secret value
r	Remove selected secret
↑/↓	Navigate list

Global keybindings

These work from any screen when not in an input field:

Key	Action
1–6	Jump to screen by number
Tab	Next screen
Shift+Tab	Previous screen
q	Quit
Ctrl+C	Quit (always, even during input)
?	Toggle help overlay (shows context-sensitive keybindings for current screen)
Shift+R	Emergency revoke epoch (double-confirm: y/n then type REVOKE)
Shift+S	Stop gate (confirmation required; only available when gate was started via up)

Emergency revoke (Shift+R)

Advances the revocation epoch from within the TUI — the same operation as latchgate revoke on the CLI. Because this immediately invalidates all outstanding execution grants, it requires double confirmation:

1. A dialog asks y/n.
2. If y, a text input requires typing REVOKE exactly. Any other text or Esc cancels.

Gate lifecycle

When the gate was started via latchgate up, the TUI can stop (Shift+S) and restart it. The restart flow stops the gate, suspends the TUI to print startup output, then resumes with the new configuration. When the gate is externally managed (systemd, Docker Compose, serve), these actions display a flash message directing the operator to the host.

Connection handling

The TUI polls the gate on a 3-second tick interval. If the gate becomes unreachable, the TUI enters a reconnect loop with exponential backoff (1 s → 2 s → 4 s → … capped at 30 s). The title bar shows ○ disconnected while disconnected and ● when connected, along with the gate mode (up, serve, or ext).

The TUI does not exit on connection loss — it keeps retrying so the operator does not lose their session when the gate restarts.

Status bar

The bottom two rows show a context-adaptive hint line (keybindings relevant to the current screen and state) and a flash message area. Flash messages (success, error, info) appear for 5 seconds (success) or 10 seconds (error) after an action completes.

Relationship to CLI

The TUI supplements the CLI — it does not replace it. The CLI remains the primary interface for scripting, CI pipelines, and non-interactive operation. Every action available in the TUI is also available via CLI commands.

For the CLI approval workflow, see latchgate approvals. For audit queries, see latchgate audit. For domain management, see latchgate domains.