--- 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. 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`). ## Enroll a machine in Fleet (`SSG_FLEET_CODE`) A Pro subscription includes Fleet. Open https://fleet.sigmashake.com/welcome to get a one-time command. The command carries a fleet code (32 hex characters, valid 15 minutes, one use). Run the command as shown. Do not edit it. Linux and macOS: ```sh curl -fsSL https://install.sigmashake.com | SSG_FLEET_CODE= sh ``` Windows PowerShell: ```powershell $env:SSG_FLEET_CODE=''; irm https://install.sigmashake.com/install.ps1 | iex ``` What the installer does when `SSG_FLEET_CODE` is set: 1. It checks the code format before it downloads anything. A bad code stops the install with exit code 4. 2. It treats the code as acceptance of the Terms of Service (https://sigmashake.com/terms). It records the consent method as `env:SSG_FLEET_CODE`. You do not need `-y`. 3. It installs `ssg`. It then runs `ssg fleet enroll`. The code goes to that command through the environment only, never as an argument. The installer removes the code from the environment right after. Enrollment also activates the license. 4. It runs `ssg init -y --accept-terms`. It restarts the governance daemon if the daemon already runs, or starts it if not. 5. It skips the account-link step unless `SSG_INSTALL_TOKEN` is also set. 6. It runs `ssg status`, then prints the line `Fleet: this machine is enrolled. Watch it connect at https://fleet.sigmashake.com/welcome`. Exit codes: - `0`: the install and the enrollment worked. No step is needed. - `3`: a step failed, but the install is in place. Read the installer output, then run the failed step again. - `4`: the fleet code is invalid. Get a new command and run it again. - `5`: fleet enrollment failed. The code can be expired, used, or revoked. Get a new command and run it again. Setup must run. Do not combine `SSG_FLEET_CODE` with `--no-setup`. The installer then warns and does not enroll. The timing line and `install-timing.json` include `fleet_ms`. --- ## 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 by default; the design target is under 2 ms per evaluation. The only published measurement is the 2026-06-10 sigmashake-bench daemon-socket run (ssg 0.29.156, n=500): p50 0.39 ms, p99 1.91 ms. If you enable the opt-in Jev assist (bring-your-own TypeSafe key), `ssg eval` also sends the tool name and input to api.typesafe.ai. Decisions (allow, log, ask, or block) are recorded to the local audit log on a best-effort basis: entries can be dropped if the daemon queue is full, and old rows are deleted at the row caps. 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.