Use the governed terminal

By the end of this tutorial you'll have a real shell open in your browser — on any OS — where every command you or an agent types is evaluated by SigmaShake before it runs, with the same allow/deny/ask rules that govern your AI agent's tool calls.

Hand this to your AI agent

Open the SigmaShake governed terminal and confirm it's protecting commands
correctly. Use only read-only commands until I tell you to open the
dashboard myself.

1. Run `ssg dashboard` and show me the URL it prints (it includes an auth
   token). Do not run `ssg serve --stop` or change the port.
2. If the daemon isn't running, run `ssg daemon --status` and tell me
   plainly whether it's up. Don't start it yourself unless I ask —
   `ssg serve` also opens a browser tab, which I'd rather do myself.
3. Explain in 3 sentences: what the governed terminal is, why a command
   typed by hand goes through the same rules as a tool call from you, and
   what "fail closed" means if the ssg binary becomes unreachable mid
   session.
4. Tell me the URL to open (`http://127.0.0.1:5599/terminal`) and remind me
   the token in the URL is a live secret — I should not paste it into chat.

What your agent will do

• Print the dashboard URL and daemon status using read-only commands only.
• Explain the governed terminal's fail-closed model in plain language.
• Stop short of opening a browser or starting the daemon — that's on you, since the URL carries a live auth token.

What you do yourself: open the URL, and if you want an AI agent running inside the pane, launch it there.

Step by step

1. Start the dashboard

ssg serve

This starts the local dashboard (default port 5599, bound to 127.0.0.1) and auto-starts the eval daemon if it isn't already running. Token auth is on by default — the URL with the token embedded is printed on startup and opens automatically in your browser unless you pass --no-browser. To see the URL again later without restarting:

ssg dashboard url

2. Open the Terminal tab

In the dashboard, click Terminal in the sidebar, or navigate directly to /terminal. This works exactly the same way on Linux, macOS, and Windows — it's a browser terminal (xterm) running a real shell process on your machine, not a remote sandbox.

There is no separate terminal subcommand in the CLI — the governed terminal only exists inside the dashboard.

3. Create a session

Click New Session (or use the leader-key binding once you've set one up — see step 6). Each session is a real shell process with its own working directory, scrollback, and lifecycle. Sessions persist across dashboard reloads: closing the browser tab doesn't kill the shell, it goes dormant and can be reattached later from the same Terminal tab.

4. Type a command — and watch it get governed

Type any command that one of your rules covers — for example, a write into a path your .rules protects, or a package-manager install if you have a rule gating those. Before the shell executes it, SigmaShake synthesizes the command into the same tool-call shape your AI agent's actions are evaluated as, and runs it through your .rules. If a rule matches with DENY, the command is blocked and the reason is printed in the pane instead of running. If a rule matches with ASK, the terminal itself prompts you inline right in the pane — [SSG] GOVERNANCE: <reason> followed by Allow anyway? [y/N] — and waits for your y/N (Enter alone counts as no). This resolves entirely in the terminal session: it needs no dashboard approval and no ssg serve/dashboard connectivity, so an ASK rule never hard-blocks you just because the dashboard's approval channel happens to be unreachable.

How enforcement actually intercepts the line (this differs by shell, and it matters if you use custom shell config):

Shell	Mechanism
zsh	A ZLE accept-line widget override — evaluated before the line is accepted, not in preexec (which fires after a line is already committed to run and can't cancel it). Installed via a temporary ZDOTDIR that restores your real .zshenv afterward.
bash	A DEBUG trap combined with shopt -s extdebug, installed via bash --rcfile for interactive sessions or BASH_ENV for non-interactive ones. A non-zero return from the trap skips the about-to-run command.
PowerShell	A PSReadLine Enter key-handler (Set-PSReadLineKeyHandler -Chord Enter). If PSReadLine can't be loaded, the session fails closed with a red [SSG] BLOCKED message rather than falling back to ungoverned execution.
cmd.exe	Not supported — it's excluded on Windows for being ungovernable rather than shipped half-patched. Use PowerShell.

The guard resolves the ssg binary path once, at session start, and freezes it — so a live export SSG_BIN=/bin/true from inside an already-open session can't silently retarget enforcement at a no-op.

Fail-closed by design: if the ssg binary is missing or ssg hook eval returns something unexpected, the command is denied and the reason is printed — never silently allowed.

5. Launch an AI agent inside a governed pane

Click the agent launcher in the session toolbar to see which coding agents are detected on your $PATH: Claude Code, Codex, Gemini CLI, Aider, OpenCode, Cursor Agent, and Pi Agent are all recognized out of the box. Pick one to launch it with its normal command inside the pane — every command it runs is now governed the same way your own typed commands are, because the agent is just another process inside the same guarded shell.

If an agent supports session resumption (Codex, Gemini CLI, OpenCode, Cursor Agent), the launcher offers a "resume last session" option instead of always starting fresh.

6. Set up keybindings (optional, one-time)

The first time you open the Terminal tab, a keybinding setup wizard walks you through picking a leader chord (tmux users will recognize familiar choices like Ctrl+b or Ctrl+a in the option list) and binding actions like new window, horizontal/vertical split, and your default agent. It won't reopen automatically once you finish it. To see every current binding at any time, open the which-key popup from the Help control in the toolbar.

7. Reattach a dormant session, or deep-link to one

Sessions list shows both live and dormant sessions. Click any entry to reattach — the shell process and its scrollback survive even if no browser tab was watching it. Other parts of the dashboard (for example, clicking Enable on the Firewall page) can hand you off directly to a specific session via /terminal?session=<id> — you land in that exact pane instead of a blank one.

Verify

ssg status

Confirm Daemon and Dashboard both show as running. Then in the Terminal pane itself, run a command you know is covered by one of your rules and confirm you see either the expected output or an SSG block/ask message — never a silent pass-through with no rule evaluation at all.

If something goes wrong

Symptom	Cause	Next step
Terminal tab is blank or shows a connection error	Daemon isn't running	Run ssg daemon --status; if stopped, ssg serve restarts both the daemon and dashboard
PowerShell session shows [SSG] BLOCKED: PSReadLine is required	The PSReadLine module isn't installed or couldn't load	Install/update PSReadLine (Install-Module PSReadLine -Force), then open a new session
A rule you just added doesn't seem to be enforced in an already-open pane	The typed-command guard installs at shell startup	Close and reopen the session, or run ssg rule sync if the rule was added via the dashboard/DB path
Session disappeared entirely instead of going dormant	The underlying shell process itself exited (e.g. you typed exit)	Create a new session — dormancy only preserves sessions the daemon is still tracking a live or exited-but-restorable process for
Dashboard URL token doesn't work anymore	Token was rotated	Run ssg dashboard token for the current one, or ssg dashboard rotate if you suspect it leaked

Next

• Configure the agent sandbox — layer provider-side sandboxing under the same governed shell.
• Manage the host firewall — its Enable/Disable actions also run through this terminal.
• Dashboard — full reference for every dashboard page.