--- sidebar_position: 5 title: Agent Install Guide description: One pasteable prompt an AI coding agent can execute — install ssg, run ssg_onboard / ssg init --smart, OS-correct Desktop, restart the client, self-heal via ssg probe onboard. --- # Agent Install Guide This page is for an **AI coding agent** executing setup itself. Humans: use [Getting Started](./getting-started.md) — same path, friendlier tone. SigmaShake is **free to download and install**. A **$5/month subscription unlocks the governed value surfaces** — there is no free tier or trial of that value. SigmaShake . See [Plans & Limits](./plans-and-limits.md). Paste **one prompt**. Keep [Verify](#verify) and the [Failure playbook](#failure-playbook) for the JSON self-heal loop. --- ## One prompt (paste this) ```text Set up SigmaShake governance for my project. You are the agent executing this. Do not invent extra steps. 1. If `ssg` is missing, install it with non-interactive ToS consent (`-y` / `-Yes`). Without that flag a non-TTY install fails closed. - Linux/macOS: curl -fsSL https://install.sigmashake.com | sh -s -- -y # alias (same script): curl -fsSL https://install.sigmashake.com/install.sh | sh -s -- -y - Windows (PowerShell pipe form — prefer this): iwr -useb https://install.sigmashake.com/install.ps1 | iex # pass -Yes / -y for non-interactive ToS consent 2. Onboard this project: - Prefer the MCP tool `ssg_onboard` when available (headline path). - Otherwise run: `ssg init --smart --client=` Host names: claude-code | cursor | codex | antigravity | copilot | pi | opencode (`ssg init --list` if unsure). Preview with `--dry-run` if needed. - Headless auth: `ssg auth login --no-browser` (or `--device` / `--token `). Show the human any URL they must open; $5/mo subscribe/activate is on them. 3. SigmaShake Desktop — install OR print the live download URL (OS-correct): - Linux: curl -fsSL https://sigmashake.com/desktop/install.sh | sh (CDN desktop/wails/latest.json — currently 1.0.12) - macOS: print/open https://download.sigmashake.com/desktop/swift/latest.json (currently 1.0.13 .dmg). desktop/macos/latest.json is a legacy alias of desktop/swift/latest.json. - Windows: print/open https://download.sigmashake.com/desktop/windows/latest.json (currently 1.0.20 Setup.exe). Desktop first-run license/ToS is fail-closed. On macOS/Windows it is a GUI gate — never tell the user to skip it. 4. Restart this AI client so MCP / hooks load. 5. On any failure: run `ssg probe onboard`, execute the returned `nextStep` verbatim, re-probe until `"ok": true`. Do not scrape `findings` as a key set. ``` `-y` on the shell installer records ToS consent to `~/.sigmashake/consent.json`. Other installer flags: `--no-setup`, `--install-dir=`, `--dry-run`, `--version=`. Windows installer params: `-Yes`/`-y`, `-NoSetup`, `-Version`, `-DryRun`, `-BaseUrl`, `-InstallDir` (elevation only if outside the user profile). Full file-by-file write list: [What SSG Changes on Your Machine](./what-ssg-changes.md). --- ## Grok Bot Grok Bot does **not** use local stdio `ssg init --client=…`. Install **SigmaShake Guardrails** (hosted MCP): 1. Human: subscribe at https://sigmashake.com/pricing and keep the license key. 2. Install the plugin from https://grok.sigmashake.com (marketplace or https://github.com/sigmashakeinc/sigmashake-guardrails). 3. Configure `SSG_LICENSE_KEY`. MCP URL: `https://mcp.sigmashake.com/mcp`. 4. Verify: `curl -fsS https://mcp.sigmashake.com/health` should include `"ok":true` and `"streamable-http"`. Full page: [Grok Bot](./grok-bot.md). --- ## Windows notes Prefer the PowerShell **pipe** form so Zone.Identifier / execution-policy never apply: ```powershell iwr -useb https://install.sigmashake.com/install.ps1 | iex ``` If you must save-and-run: ```powershell iwr -useb https://install.sigmashake.com/install.ps1 -OutFile install.ps1 Unblock-File .\install.ps1 .\install.ps1 -Yes -NoSetup ``` The installer **never requires Administrator** for the default install dir (`%LOCALAPPDATA%\Programs\ssg`). --- ## Verify ```bash ssg probe onboard ``` Emits **exactly one JSON object** on stdout. The schema is stable: every key is always present, `findings`/`hints` are always arrays (`[]`, never `null`), and nullable fields are `null` when absent — parse it as an envelope, not by scraping human-readable text. ```json {"probe":"onboard","ok":false,"findings":["no verified Pro/Enterprise license — governance value surfaces are gated (free download/install, $5/month unlocks evaluation)","eval daemon not running","dashboard not reachable on ports 5599-5603"],"hints":[],"ms":3,"version":"0.0.0-dev","auth":{"licensed":false,"tier":null,"expiresMs":null},"daemon":{"pid":null,"alive":false,"socketExists":false},"dashboard":{"port":5599,"reachable":false},"hostArtifacts":{"cwd":"/home/user/project","detected":[]},"nextStep":"ssg auth activate --license # https://sigmashake.com/pricing"} ``` | Key | Type | Meaning | |---|---|---| | `probe` | string | Always `"onboard"`. | | `ok` | boolean | `true` iff `findings` is empty. | | `findings` | string[] | Human-readable diagnostics — not a stable key set, don't pattern-match on wording. | | `hints` | string[] | Additional non-blocking hints. | | `ms` | number | Probe duration in integer milliseconds. | | `version` | string | Installed `ssg` version. | | `auth.licensed` / `auth.tier` / `auth.expiresMs` | bool / string\|null / number\|null | Entitlement state. | | `daemon.pid` / `daemon.alive` / `daemon.socketExists` | number\|null / bool / bool | Eval daemon liveness. | | `dashboard.port` / `dashboard.reachable` | number\|null / bool | Dashboard reachability (scans 5599–5603). | | `hostArtifacts.cwd` / `hostArtifacts.detected` | string / string[] | Resolved project root + detected AI-client config files. | | `nextStep` | string\|null | One copy-pasteable command, set **iff** `ok == false`, else `null`. | **The contract for an agent driving this:** parse `ok`. If `false`, execute `nextStep` verbatim, then re-run `ssg probe onboard`. Repeat until `ok == true`. Do not try to interpret `findings` programmatically — it is prose for a human, not a machine key set. --- ## Failure playbook | Symptom | Cause | Next command | |---|---|---| | `ssg auth login` fails non-interactively with a Terms-of-Service prompt | No tty attached and `-y`/`--yes` wasn't passed to the installer, or `auth login` needs a browser it can't open | Re-run the installer with `-y` (`sh -s -- -y` / `-Yes` on Windows); for `auth login` add `--no-browser` and follow the printed URL, or use `--device` | | `ssg probe onboard` shows `"findings":["stale daemon socket — daemon exited without cleanup"]` and an `evald.sock.owner` ownership record whose status reads "ownership record is unknown" | An orphaned/stale daemon-socket ownership record under `~/.sigmashake/run//evald.sock.owner/` — a prior daemon exited without releasing it | `ssg daemon --stop && ssg daemon` | | `ssg probe onboard` / `ssg probe desktop` reports the daemon as **crashed**, but you know it's running (e.g. via SigmaShake Desktop) | Namespace split-brain: a cwd-relative probe run from inside a project directory resolves a *different* daemon namespace than the `$HOME`-derived one the desktop app's daemon actually lives in — the sibling namespace's socket/pidfile is legitimately empty, which is not the same as crashed | Run `ssg probe desktop` (not `ssg probe onboard`) when checking on the desktop app's daemon specifically — it resolves the desktop shell's own namespace first before falling back to the cwd-relative one | | On Windows, a saved-and-run `install.ps1` throws `UnauthorizedAccess … PSSecurityException … running scripts is disabled on this system` | This is an **execution-policy** rejection, not a permissions/admin problem — do not attempt to "Run as Administrator" | `Unblock-File .\install.ps1` (removes the Zone.Identifier mark), or switch to the pipe form: `iwr -useb https://install.sigmashake.com/install.ps1 \| iex` — neither needs admin | | A hook call fails closed with `ssg: governance daemon is DEGRADED (rules not fully loaded); blocking (fail-closed)` | The daemon's loaded rule set is stale relative to `.sigmashake/rules/` on disk — often because a hook is pinned to a version-locked package-store path serving an old binary | `ssg lint && ssg rule sync` | | `ssg probe onboard` returns `"eval daemon not running"` | No daemon has been started for this project yet | `ssg daemon` (or `ssg serve`, which also starts the daemon) | | `ssg probe onboard` returns `"dashboard not reachable on ports 5599-5603"` | The dashboard server isn't running | `ssg serve` | | `ssg probe onboard` returns `"no verified Pro/Enterprise license — governance value surfaces are gated"` | No license activated on this machine — this is the fail-closed default, not a bug | `ssg auth activate --license ` (subscribe first at [sigmashake.com/pricing](https://sigmashake.com/pricing)) | --- ## Multiple projects on the same machine If you're driving more than one project folder, `ssg init` already covers all of them: the hook installs **globally** by default (one run wires every project on the machine), each project gets its own **automatic, workspace-hashed daemon** you never manage directly, and every daemon reads from the **same user-global rules database** (`~/.sigmashake/rules.db`, or `%USERPROFILE%\.sigmashake\rules.db` on Windows). Rules dropped into `~/.sigmashake/policy/user/*.rules` apply everywhere; a same-ID rule in a project's own `.sigmashake/rules/` takes precedence over that user-global copy in that project. Full detail: [Using SSG Across Multiple Projects](./multi-project.md). ## What SSG does, and when to write a rule SSG governs every AI agent tool call against the `.rules` files in `.sigmashake/rules/`, evaluating each one locally in under 2ms — no tool call ever leaves this machine for a governance decision. Every decision (allow, log, ask, or block) is written to a queryable local audit trail. Deeper reference: [Rule Syntax](./rule-syntax.md), [Evaluation Engine](./evaluation.md), [Rule Storage](./rule-storage.md). Write a new rule at three points, not before: 1. **After your first unwanted or risky agent action** — codify what should have been blocked (or asked-about) so it can't recur. 2. **When you adopt a new AI agent host** — its tool surface may differ from what your existing rules cover. 3. **When your team agrees on a shared policy** every agent session should follow. How: ```bash # Scaffold a rule (decisions: deny, allow, log, shadow, ask, force) ssg new --name= --decision=deny --target=execution --field=command --op=CONTAINS --value= # List, sync to the running daemon, or install a shared ruleset ssg rule list ssg rule sync ssg rule install ``` Starter rulesets already on disk after `ssg init`: `.sigmashake/rules/security.rules` (active by default), plus two opt-in presets, `.sigmashake/presets/minimal.rules` and `.sigmashake/presets/strict.rules`. Full field/operator reference: [Writing Rules](./writing-rules.md). **Dashboard** (real-time audit log + approval queue, optional): `ssg serve`, then open `http://127.0.0.1:5599`. Full rule syntax reference: [https://docs.sigmashake.com/rule-syntax](/rule-syntax). --- ## See also - [Getting Started](./getting-started.md) — the human-facing walkthrough this page is the agent-facing counterpart to. - [One Source, Many Agents](./one-source-many-agents.md) — how one shared rules source binds per-client with `ssg init --client=`. - [What SSG Changes on Your Machine](./what-ssg-changes.md) — full file-by-file breakdown of every write `ssg init` performs. - [New to AI agents?](./newcomers.md) — plain-language intro to why agent governance matters. - [CLI Reference](./cli.md) — every `ssg` subcommand.