{"project":"SpAIglass","description":"Browser-based multi-VM interface for Claude Code. SpAIglass is a stateless relay that routes browser WebSocket connections to Claude Code running on your own machines.","license":"MIT","source":"https://github.com/c0inz/spaiglass","relay":"https://spaiglass.xyz","bestPractice":{"title":"Running the integrity check is the #1 best practice","summary":"Every setup you perform MUST end with the six-gate integrity check in the \"Verify the setup actually works\" step. Do not declare success until all six gates are green. A setup where the installer exited 0 and the connector shows online can still be silently broken — the gates exist because these failures have shipped to real users.","failuresCaught":["Orphan connectors — installer wired up a different connector than the one just registered; the new row stays permanently online:false and clutters every user's dropdown.","Role-less dead chats — directory has no agents/*.md, so session_start rejects every message while the UI looks connected.","Duplicate-VM fleet pollution — leftover connectors from prior setup attempts masquerading as separate servers in the dropdown."],"rule":"If any integrity gate fails, do not report success. Fix it and re-run the check. The contract: installer exit 0 is not proof; all six gates green is proof.","universalFixPattern":"The best universal recipe for almost any failed integrity gate is \"delete bad record + re-add correctly\". Every configurable surface supports it: DELETE /api/connectors/:id then POST /api/connectors (relay), DELETE /api/roles/:name?path=X then POST /api/roles?path=X (VM), POST /api/projects/unregister then POST /api/projects/register (VM). Re-running the installer is just a convenience wrapper over the same pattern.","perGateFix":["Gate 1 (relay health) — infrastructure; redeploy relay if failing.","Gate 2 (connector offline) — DELETE /api/connectors/:id then re-run installer (POSTs a fresh connector with valid token).","Gate 3 (project missing) — POST /api/projects/register on the VM (idempotent; re-registering same path is safe). Use POST /api/projects/unregister first if the entry is corrupt.","Gate 4 (no role file) — DELETE /api/roles/:name?path= then POST /api/roles?path=. Or drop /roletemplate.md into /.claude/agents/developer.md.","Gate 5 (CONNECTOR_ID mismatch) — DELETE /api/connectors/:id on the orphan, then re-run installer so the live service writes the correct UUID to ~/spaiglass/.env.","Gate 6 (duplicate/legacy connectors) — DELETE /api/connectors/:id on each orphan; keep the one whose UUID matches the live ~/spaiglass/.env."]},"model":{"title":"Mental model: Server + Directory (read this first)","summary":"SpAIglass now works on two concepts — Server and Directory. Everything below assumes this model. If you are an agent reading this to configure a new user, internalize the terms before touching any endpoints.","points":["Server = one connector = one machine. The user picks a server from a dropdown in the UI. Internally each server has a connector name (URL slug) and a displayName (human label). The fleet API calls these rows \"connectors\"; the UI calls them \"Servers\". Same thing. One agent key can own many servers.","Directory = one project folder on a server. In the UI this is a dropdown populated from the server's GET /api/projects (Claude Code's own project registry at ~/.claude.json). One server can have many directories — a user is no longer forced into one-connector-per-project. The UI term is always \"Directory\", never \"Folder\" — do not rename it in user-facing copy.","Role is optional. A role file (.claude/agents/<role>.md) defines persistent Claude persona + plugins + tool allowlist for a directory. If a directory has no role, chat still works — you just get the default Claude Code behavior. Add roles when the user wants persistent persona or plugin pinning; skip them for casual exploration.","URL shapes. /vm/<login>.<server>/ → Server+Directory picker. /vm/<login>.<server>/<directory-basename>/ → chat for that directory (role-less; primary flow). /vm/<login>.<server>/<directory>-<role>/ → chat with a specific role (legacy but still supported for links/bookmarks). The human never needs to know any of these — they use dropdowns.","Migration from old single-project connectors. Existing connectors keep working as-is. They just become \"servers\" in the new vocabulary. The old one-connector-per-project habit is no longer necessary — consolidate by pointing one connector at a server with several ~/projects/* directories. Nothing in the DB needs migrating."]},"supportedPlatforms":{"hosts":[{"os":"Linux","detail":"Ubuntu / Debian / Fedora / Arch — anything with bash, tar, node>=20. Installs as a systemd --user service with linger."},{"os":"macOS","detail":"macOS 12+ on Intel or Apple Silicon. Installs as a launchd LaunchAgent under ~/Library/LaunchAgents."},{"os":"Windows","detail":"Windows 10 build 17063+ / Windows 11. Installs as a per-user Scheduled Task that runs at logon (no admin needed)."}],"claudeCli":"Anthropic's Claude Code CLI must be installed and authenticated on the host before running the spaiglass installer. See https://claude.ai/install.sh (Linux/macOS) or https://claude.ai/install.ps1 (Windows)."},"steps":[{"title":"Check what already exists (do this FIRST)","description":"Before registering anything, find out whether this user already has a connector set up. This step prevents the #1 fleet-maintenance bug: agents re-registering a VM the user already owns, leaving duplicate or stale connectors behind.

1. Do you already have an agent key? If your human user has handed you an sg_... key, use it. If not, skip to Step 2 to mint one — you need it to call GET /api/connectors.

2. List existing connectors. Call GET https://spaiglass.xyz/api/connectors with your agent key. If the VM you are being asked to configure already appears in the list, do NOT create a new one — reuse it. If only the human-friendly name is wrong, use PATCH /api/connectors/:id with {\"name\": \"new-slug\"} to rename in place (preserves id + token, VM keeps running).

3. Ask the human when in doubt. If the list has a connector that might be the target VM (same prefix, similar name), ask the human before touching it — do not guess.","endpoint":"GET https://spaiglass.xyz/api/connectors","note":"Requires `Authorization: Bearer sg_YOUR_KEY` header. Response is a flat array of `{id, name, displayName, role, online, lastSeen, ...}`. This is the source of truth for the fleet dropdown — anything in it is real, anything not in it does not exist."},{"title":"Get an agent key (two options)","description":"You need an sg_... agent key before you can register a VM. Pick whichever option fits how your human user is set up:

Option A — You already have your user's GitHub PAT. Exchange it for an agent key via the API below. This is the fastest path when you (the agent) already have credentials. A classic PAT needs no scopes (the relay only calls GET https://api.github.com/user). A fine-grained PAT needs Account permissions → Read profile data — no repo scopes.

Option B — Ask the human to retrieve a token. Tell the user: \"Go to https://spaiglass.xyz and sign in with GitHub. If you have no VMs registered yet, a one-shot token will appear in a copy-box — paste it back to me.\" That token is a real sg_... agent key minted for their session. Either option produces the same kind of key; use Option B whenever you do not already have a PAT and do not want to ask for one.","endpoint":"POST https://spaiglass.xyz/api/auth/token-exchange","body":"{ \"github_pat\": \"github_pat_YOUR_TOKEN\", \"key_name\": \"my-agent\" }","note":"Token prefix: fine-grained PATs start with `github_pat_` (the default when you create one in GitHub today); classic PATs start with `ghp_`. Either one is accepted — send the string you have, whichever prefix it has. Save the returned agent key — it is shown only once. Treat it like a password. All subsequent steps set the header `Authorization: Bearer sg_YOUR_KEY`."},{"title":"Register a VM","description":"Register a new VM connector. The name is a short label for your reference (used as the URL slug the human will see later). You can register one VM, or one for each project you are setting up — the agent key is reusable across VMs.

Name rules (enforced on create AND rename — same contract): must start alphanumeric, can contain letters, digits, dots, hyphens, underscores; max 100 chars; cannot be a reserved relay route (e.g. api, vm, setup, auth, install, releases, dashboard). Whitespace-only or empty names are rejected. A 409 means you (the same user) already have a connector with that name — check Step 1's list and reuse it, or pick a different name.

Want a different name later? Use PATCH /api/connectors/:id with {\"name\": \"new-slug\"}. That preserves the id and token so the VM-side connector keeps working without reconfig — see the Fleet Management API section below.","endpoint":"POST https://spaiglass.xyz/api/connectors","body":"{ \"name\": \"my-vm\" }","note":"Requires `Authorization: Bearer sg_YOUR_KEY` header. The response returns `{ id, name, token, ... }` — save all three, `token` is shown ONCE and you'll feed all three to the installer in the next step. `id` and `token` are both UUIDs (no prefix); `name` is the slug you just chose.\n\nWorked example mapping this response to Step 5 flags:\n Response: { \"id\": \"4f5e...\", \"name\": \"my-vm\", \"token\": \"8a9b...\" }\n Step 5: --id=4f5e... --name=my-vm --token=8a9b...\nCopy each field verbatim. Do not invent values. Do not reuse the agent key (sg_...) as the connector token — they are different credentials. You do NOT need to construct or remember a VM URL; sign-in handles routing for the human automatically."},{"title":"Install Claude Code CLI on the host","description":"SpAIglass spawns the official Anthropic Claude Code CLI to run sessions. It must be installed AND authenticated before the spaiglass installer runs.

Auth model — read this first. Both auth patterns below use your existing Claude subscription via OAuth. Neither one generates or uses an ANTHROPIC_API_KEY; nothing here switches you to API-key billing. The terms \"headless\" and \"setup-token\" sound like API-key flows but they are not — they are just OAuth tokens stored on disk so non-interactive subprocesses can read them. SpAIglass spawns claude as a subprocess; it inherits whichever credentials file you produce here.

Pick the right pattern for the host:

Pattern A — Desktop with a browser (Windows, macOS, Linux desktop). Run claude login once. The CLI opens your default browser, you complete OAuth, the credentials persist to ~/.claude/.credentials.json (Linux/macOS) or %USERPROFILE%\\.claude\\.credentials.json (Windows). Use this on any machine where you can reach the browser yourself.

Pattern B — Headless VM (no desktop, SSH-only). Plain claude login hangs waiting for a TTY/browser that is not there. Run claude setup-token on the VM instead — it prints a URL, you open it in a browser on any other machine, complete OAuth, paste the code back into the VM terminal. Same OAuth subscription, just a one-round-trip flow that doesn't need a browser on the VM itself.

Pattern C — Cloning credentials (fleet rollouts). If you already authenticated on another machine, copy ~/.claude/.credentials.json to the new host (same path, mode 600 on Linux/macOS). Same OAuth subscription, no second login.

Verify with claude --version AND a trivial round-trip (echo hi | claude -p 'say ok') before continuing. A claude binary that responds to --version but 401s on -p will cause the spaiglass installer to look fine while every chat session dies on first message.","requirements":["Node.js >= 20","Claude Code CLI installed (~/.local/bin/claude on Linux/macOS, %USERPROFILE%\\.local\\bin\\claude.exe on Windows)","Claude Code CLI authenticated via OAuth (subscription) — verify with: echo hi | claude -p 'say ok'"],"commands":["# ── Install ──","# Linux / macOS:","curl -fsSL https://claude.ai/install.sh | bash","","# Windows (PowerShell):","irm https://claude.ai/install.ps1 | iex","","# ── Authenticate (pick ONE; both are OAuth subscription, NOT API key) ──","","# Pattern A — Desktop with a browser (Windows, macOS, Linux desktop):","claude login","# Opens your default browser, complete OAuth, done.","","# Pattern B — Headless VM (SSH-only, no GUI):","claude setup-token","# Prints a URL. Open on any machine with a browser, complete OAuth,","# paste the returned code back into the VM terminal.","","# ── Verify auth actually works (not just that the binary exists) ──","claude --version","echo hi | claude -p 'say ok' # should print an assistant reply"],"note":"SpAIglass looks for the binary at ~/.local/bin/claude on Linux/macOS and %USERPROFILE%\\.local\\bin\\claude.exe on Windows. If `claude -p` fails with 401/403, re-run `claude login` (desktop) or `claude setup-token` (headless) — tokens occasionally expire before paste. Do NOT set ANTHROPIC_API_KEY; SpAIglass uses your OAuth subscription. Do NOT run plain `claude login` on a headless VM expecting it to auth — it needs a TTY and a local browser. Use `claude setup-token` there instead."},{"title":"Install spaiglass on the host (one liner)","description":"The installer downloads a self-contained binary tarball (~30 MB) from the relay, extracts it under ~/spaiglass, writes the .env, and registers a per-user service that launches the backend + relay connector at boot/logon. Idempotent. Re-running upgrades in place and preserves the existing .env — if setup failed partway through, you (the agent) can re-run the exact same one-liner with the original --token/--id/--name, or without any flags to refresh from the saved .env.

Linux gating decision — user lingering (requires sudo). On Linux, the systemd --user service only survives logout if lingering is enabled for the user, and enabling lingering is a root-only operation. Before running the installer, check whether passwordless sudo is available: sudo -n loginctl enable-linger $USER. If that succeeds silently, you are done — proceed to install. If it fails (prompts for a password or exits non-zero), stop and ask the human user to run it manually — without linger the service will die on logout and the VM will appear to \"go offline\" mysteriously. The installer itself hard-fails on Linux when linger is not set, so there is no way to sleepwalk past this. macOS and Windows have no linger requirement.","commands":["# Linux preflight (ask the user to run if this errors):","sudo -n loginctl enable-linger $USER","","# Field mapping — use the EXACT values from Step 3's response:","# --id= (UUID)","# --name= (the slug you chose)","# --token= (UUID, shown once)","","# Linux / macOS install:","curl -fsSL https://spaiglass.xyz/install.sh | bash -s -- \\"," --token=YOUR_TOKEN --id=YOUR_ID --name=YOUR_VM_NAME","","# Windows (PowerShell — run as your normal user, no admin needed):","& ([scriptblock]::Create((iwr https://spaiglass.xyz/install.ps1 -useb))) `"," -Token YOUR_TOKEN -Id YOUR_ID -Name YOUR_VM_NAME"],"note":"Installs a systemd --user unit on Linux, a launchd LaunchAgent on macOS, and a per-user Scheduled Task on Windows. All three start automatically and restart on crash. No inbound ports are opened — the connector dials out over WSS to the relay. If the installer bails on the linger check, fix linger and re-run the same one-liner.\n\nSupported hosts: Linux x64/arm64, macOS x64/arm64, and Windows x64 — five native binaries, no WSL2 required. The PowerShell installer pulls the matching windows-x64 build automatically. Files land under %USERPROFILE%\\spaiglass\\ on Windows (env file: %USERPROFILE%\\spaiglass\\.env)."},{"title":"Optional: add a role file to a directory","description":"Roles are optional in the Server+Directory model. A directory without a role works fine — chat uses default Claude Code behavior for that cwd. Add a role when the user wants a persistent persona, a pinned plugin set, or a restricted tool allowlist for that directory. If the user has not asked for one, skip this step — do not hand-craft a role file unprompted.

When you do add a role: SpAIglass uses Claude Code's native .claude/agents/ directory — the same convention the CLI uses with claude --agent <name>. Each .md file becomes a selectable role for that directory in the SpAIglass chat view.

Fastest path — use the register API. One POST to the VM's local backend creates the directory, role file, Claude config entry, and project metadata directory in one shot. See Adding Projects & Roles for the endpoint reference.

Manual path (same result). If you prefer shell commands, the block below works. After creating the file, restart the spaiglass service (systemctl --user restart spaiglass) so the backend re-scans.

Start from the baseline. Do not block on hand-crafting a role. There is a canonical template at /roletemplate (raw: /roletemplate.md). Drop it in, finish setup, and then discuss with the human how to improve the role.md during the first real session.","commands":["# ── RECOMMENDED: one-shot register via API ──","curl -s -X POST http://127.0.0.1:8080/api/projects/register \\"," -H 'Content-Type: application/json' \\"," -d '{\"name\": \"MyProject\", \"role\": \"developer\"}'","","# With custom role content:","curl -s -X POST http://127.0.0.1:8080/api/projects/register \\"," -H 'Content-Type: application/json' \\"," -d '{\"name\": \"MyProject\", \"role\": \"developer\", \"roleContent\": \"You are the developer for MyProject...\"}'","","# ── Manual path (if you prefer shell commands) ──","PROJECT=myproject","ROLE=developer","mkdir -p ~/projects/$PROJECT/.claude/agents","curl -fsSL https://spaiglass.xyz/roletemplate.md \\"," | sed \"s//$PROJECT/g\" \\"," > ~/projects/$PROJECT/.claude/agents/$ROLE.md","systemctl --user restart spaiglass # re-scan projects"],"example":"https://spaiglass.xyz/vm/octocat.dev-server/myproject-developer/","note":"SpAIglass also checks the legacy agents/ directory for backward compatibility. If the same filename exists in both .claude/agents/ and agents/, the .claude/agents/ version takes precedence. The canonical baseline template is at /roletemplate — use it whenever a setup agent would otherwise block on \"what should the role file say?\".","roleFrontmatterSchema":{"description":"Role files use YAML frontmatter (between --- delimiters) to configure plugins, tools, MCP servers, and model settings. The markdown body below the frontmatter is injected into Claude's system prompt.","fields":[{"name":"plugins","type":"object","description":"Enable/disable plugins for this role: \"plugin-name@marketplace\": true/false. Parsed from role frontmatter and surfaced in the role editor UI."},{"name":"mcpServers","type":"object","description":"MCP tool servers to register for this role's sessions. Same format as Claude Code's mcpServers config."},{"name":"tools","type":"string[]","description":"Allowlist of tools this role can use (e.g., Read, Write, Bash, mcp__github__*)."},{"name":"disallowedTools","type":"string[]","description":"Tools to block for this role, even in bypass mode."},{"name":"model","type":"string","description":"Claude model override (e.g., claude-opus-4-6, claude-sonnet-4-6)."},{"name":"permissionMode","type":"string","description":"Permission mode override (bypassPermissions is the default in SpAIglass)."},{"name":"maxTurns","type":"number","description":"Max conversation turns before the session stops."},{"name":"effort","type":"string","description":"Thinking effort level (low, medium, high)."}],"example":"---\nplugins:\n superpowers@claude-plugins-official: true\n code-review@claude-plugins-official: true\n frontend-design@claude-plugins-official: false\nmcpServers:\n github:\n command: npx\n args:\n - -y\n - \"@anthropic-ai/mcp-server-github\"\ntools:\n - Read\n - Write\n - Edit\n - Bash\n - mcp__github__*\nmodel: claude-opus-4-6\n---\n# MyProject — Backend Developer\n\nYou are the lead backend engineer..."},"roleConfigDir":{"title":"Plugin enablement per role","description":"SpAIglass parses the enabledPlugins map from each role's frontmatter and surfaces it in the role editor UI. Sessions for all roles currently share the host's ~/.claude/ config — per-role plugin settings aren't physically isolated yet, so if two roles enable conflicting plugins, the last-written settings win. Keep plugin sets aligned across roles on the same project for now."},"roleChecklist":[{"section":"Identity (put first)","description":"Who is Claude in this role? \"You are the lead backend engineer for ProjectX.\" One strong sentence at the very top. Models attend most to the beginning and end of instructions — put identity and hard rules at those positions."},{"section":"Project location","description":"Where is the code? ~/projects/myproject/ — Claude needs this to find files without asking."},{"section":"Architecture / tech stack","description":"What's the stack? What are the key directories? Use tables — a table of 10 directories with one-line descriptions beats two paragraphs of prose. Only list things Claude can't figure out by reading the code."},{"section":"How things connect","description":"How do the pieces connect? How do messages flow? How is it deployed? Write this like a day-one briefing for a new developer, not a reference manual."},{"section":"Verification commands","description":"How does Claude check its own work? Provide the exact commands: build, test, lint, deploy-check. This is the single highest-leverage section — without it, you become the only feedback loop."},{"section":"Authority & access","description":"What can Claude do? sudo, git push, SSH to other machines, credentials, databases. If Claude doesn't know it has access, it won't use it. List credential file paths explicitly."},{"section":"Conventions","description":"Commit message style, branch strategy, test expectations, naming conventions. Only include rules that differ from defaults — don't tell Claude to \"write clean code.\""},{"section":"Compaction instructions","description":"What must be preserved when Claude's context window compresses during long sessions? \"Always preserve: modified file list, pending deploys, current task, verification commands.\" Without this, long sessions lose critical state."},{"section":"Hard rules (put last)","description":"What must Claude NEVER do? Use absolute language (NEVER, MUST NOT) and explain WHY for each rule. \"Never force-push to main — other sessions depend on linear history.\" Rules with rationale are followed more reliably than bare commands."}],"roleAntiPatterns":["Flattery (\"you are an EXTREMELY TALENTED genius engineer\") — does nothing measurable, wastes tokens","Step-by-step scripts — contradicts autonomous agent behavior. State what \"done\" looks like, not how to get there","Knowledge dumps — don't paste API docs or file-by-file descriptions. Link to them or let Claude read the code","Linter rules — use actual linters and hooks for formatting, not prose instructions Claude might forget","Repeating what Claude already knows — standard language conventions, obvious best practices, \"write tests\"","Over 200 lines — bloated role files cause Claude to skim or ignore your actual instructions"],"roleExample":"---\nplugins:\n superpowers@claude-plugins-official: true\n code-review@claude-plugins-official: true\nmodel: claude-opus-4-6\n---\nIMPORTANT: You are the lead backend engineer for MyProject, a SaaS API platform. You are a senior engineer with root access. Execute, don't narrate.\n\n## Who you are\n- You own the backend: API, database, deployment pipeline\n- The human is technical and direct — report results, not intentions\n- When something breaks, diagnose the root cause. Don't retry blindly\n\n## Project\n~/projects/myproject/ — GitHub: github.com/acme/myproject (main)\n\n## Architecture\n| Layer | Stack |\n|-------|-------|\n| API | Node.js 20, Express, TypeScript |\n| Database | PostgreSQL 16 on db.internal:5432 |\n| Cache | Redis on cache.internal:6379 |\n| Deployment | Docker Compose via `./scripts/deploy.sh` |\n\n## Key directories\n| Path | What's there |\n|------|-------------|\n| src/routes/ | API route handlers |\n| src/models/ | Database models (Drizzle ORM) |\n| src/middleware/ | Auth, rate limiting, logging |\n| tests/ | Vitest test suite |\n| scripts/ | Deploy, migrate, seed scripts |\n\n## Verification — check your work\n| What | Command |\n|------|---------|\n| Types compile | `npx tsc --noEmit` |\n| Tests pass | `npm test` |\n| Lint clean | `npm run lint` |\n| DB migrations | `npm run migrate:status` |\n\nALWAYS run the relevant checks before declaring done.\n\n## Access & credentials\n- `~/credentials/db.json` — PostgreSQL connection string\n- `~/credentials/github.json` — PAT (git push works via credential helper)\n- SSH to db.internal and cache.internal via ~/.ssh/config\n- Passwordless sudo on this machine\n\n## Conventions\n- Commit messages: imperative mood (\"Add user endpoint\", not \"Added\")\n- PRs target main, squash-merge only\n- Migrations in src/migrations/ — never edit a shipped migration\n\n## When context compacts\nPreserve: list of modified files, pending deploys, current task, test results.\n\n## IMPORTANT — Hard rules\n- NEVER commit anything from ~/credentials/. Why: live tokens would be exposed in git history.\n- NEVER force-push to main. Why: CI and other developers depend on linear history.\n- NEVER drop a production table without explicit instruction. Why: data loss is irreversible."},{"title":"Managing the Directory dropdown (hide / add / rename)","description":"The Directory dropdown in the SpAIglass chat header is a live view of Claude Code's ~/.claude.json projects map on this VM — SpAIglass does not maintain its own separate list. To change what the human sees in the dropdown, mutate ~/.claude.json via the three VM-local endpoints below. The user will typically ask you in chat (e.g. \"hide the workspace directory\", \"add ~/code/foo\", \"rename that one to Acme API\") — make the matching API call and confirm. The next page reload on the user's side picks up the change; no restart needed.

Hide a directory — removes the entry from ~/.claude.json but keeps its encoded session history on disk, so re-registering later restores prior chats.

Add a directory — the same register endpoint used at setup time. Role is optional in the Server+Directory model; pass {\"name\": \"...\"} alone to just create the directory entry.

Rename (cosmetic label only) — the directory's real path never changes; this just overrides the display name in the dropdown.

These calls are VM-local (127.0.0.1:8080) and require no auth — only the VM-side agent can reach them.","commands":["# ── Hide a directory from the dropdown ──","curl -s -X POST http://127.0.0.1:8080/api/projects/unregister \\"," -H 'Content-Type: application/json' \\"," -d '{\"path\": \"/home/user/workspace\"}'","# → {\"ok\":true,\"removed\":true,\"path\":\"/home/user/workspace\"}","# Idempotent: removed:false if the path was not registered.","","# ── Add a directory to the dropdown ──","curl -s -X POST http://127.0.0.1:8080/api/projects/register \\"," -H 'Content-Type: application/json' \\"," -d '{\"name\": \"foo\"}' # ~/projects/foo, no role","","# Add with an explicit absolute path (anywhere on disk):","curl -s -X POST http://127.0.0.1:8080/api/projects/register \\"," -H 'Content-Type: application/json' \\"," -d '{\"name\": \"foo\", \"path\": \"/home/user/code/foo\"}'","","# ── Rename the dropdown label (cosmetic) ──","# `project` is the directory basename (e.g. 'foo' for /home/user/code/foo),","# NOT the full path. Pass displayName:null to clear the override.","curl -s -X PUT http://127.0.0.1:8080/api/settings/project-display-name \\"," -H 'Content-Type: application/json' \\"," -d '{\"project\": \"foo\", \"displayName\": \"Acme API\"}'","","# ── See what is currently in the dropdown ──","curl -s http://127.0.0.1:8080/api/projects | jq"],"note":"These mutate ~/.claude.json directly. Hide preserves session transcripts under ~/.claude/projects// so re-adding the same path restores history. Directories under ~/spaiglass, ~/.spaiglass, and ~/.claude are filtered from the dropdown automatically — do not try to hide those, they are already invisible."},{"title":"Verify the setup actually works","description":"Do NOT trust \"installer exited 0\" as proof of working. The service can fail to start, the connector token can be wrong, linger can silently revert — all of which leave the installer happy but the VM absent from the fleet.

1. Relay health (public). GET https://spaiglass.xyz/api/health — returns {\"status\":\"ok\", \"spaiglassVersion\":\"...\"}. No auth required. Confirms the relay is reachable from wherever you are calling from.

2. Connector online (authenticated). GET https://spaiglass.xyz/api/connectors and look for your id with online: true. If online: false 30 seconds after the installer finished, the service did not attach — see troubleshooting.

3. Project visible (on the VM). GET http://127.0.0.1:8080/api/projects on the VM itself should return the project you just registered. If it does not, either the backend is not running on port 8080 or the project was written to the wrong directory.

4. Directory has a resolvable role. GET http://127.0.0.1:8080/api/roles?path=<projectPath> must return a non-empty roles array. The backend session store is keyed by (projectPath, roleFile) — a directory with zero role files cannot start a session even though chat URLs resolve and the connector looks online. The browser's role-less URL flow (/vm/<server>/<directory>/) auto-picks developer.md if present, else the first available file; if the list is empty, chat silently dies at session_start. If this check returns { \"roles\": [] }, either (a) call POST /api/projects/register with a role name to create one, or (b) drop /roletemplate.md into <projectPath>/.claude/agents/developer.md and re-run the check.

5. Installed CONNECTOR_ID matches the one you just registered. Read CONNECTOR_ID from ~/spaiglass/.env on the VM and compare it to the id returned by Step 3's POST /api/connectors. They must be the same UUID. If they differ, the installer was run with flags from a previous registration, leaving the connector you just created as an orphan (visible in GET /api/connectors, permanently online: false, never seen by the relay) while the service is actually authenticated as a different one. Fix by calling DELETE /api/connectors/:id on the orphan — do not leave it in the fleet, it shows up in every user's dropdown as a broken server.

6. No other orphaned connectors for this host. List owned connectors via GET /api/connectors and inspect any entry with online: false AND a lastSeen either null or older than 24h. If more than one owned connector is authenticated-but-silent and they plausibly map to the same VM (same display name stem, same human’s machine), they are leftovers from a prior failed setup. One machine should equal one connector — duplicate registrations fracture the recent-URL list in the UI and make the dropdown surface dead entries. Delete the orphans with DELETE /api/connectors/:id; the live service keeps working because its token points at the row you are keeping.

Only after all six pass should you report \"setup complete\" to the human.","commands":["# From anywhere (no auth):","curl -fsSL https://spaiglass.xyz/api/health | jq","","# With your agent key (confirm connector is online):","curl -fsSL -H 'Authorization: Bearer sg_YOUR_KEY' \\"," https://spaiglass.xyz/api/connectors \\"," | jq '.[] | select(.id==\"YOUR_CONNECTOR_ID\") | {name, online, spaiglassVersion}'","","# On the VM (confirm project was registered):","curl -fsSL http://127.0.0.1:8080/api/projects | jq","","# On the VM (confirm the directory has at least one role file —","# chat silently dies at session_start if this list is empty):","curl -fsSL 'http://127.0.0.1:8080/api/roles?path=/home/USER/projects/myproject' \\"," | jq '.roles | length' # must be >= 1","","# Fix pattern if gate 4 fails — delete bad role + re-add. On the VM:","# curl -X DELETE 'http://127.0.0.1:8080/api/roles/?path='","# curl -X POST 'http://127.0.0.1:8080/api/roles?path=' \\","# -H 'Content-Type: application/json' \\","# -d '{\"name\":\"developer\",\"description\":\"...\"}'","","# On the VM (confirm the installer actually wired up the connector","# you just registered — mismatch = orphan row in the relay DB):","grep '^CONNECTOR_ID=' ~/spaiglass/.env","# The UUID printed here MUST equal the `id` from Step 3's response.","","# Orphan sweep — any owned connector that never came online, or","# last saw the relay >24h ago, that maps to this same host is dead","# weight in the dropdown. Delete each one with:","# curl -X DELETE -H 'Authorization: Bearer sg_YOUR_KEY' \\","# https://spaiglass.xyz/api/connectors/","curl -fsSL -H 'Authorization: Bearer sg_YOUR_KEY' \\"," https://spaiglass.xyz/api/connectors \\"," | jq '.[] | select(.online==false and (.lastSeen==null or (now - (.lastSeen/1000) > 86400))) | {id, name, displayName, lastSeen}'"],"note":"If any of the six checks fail, stop and consult the troubleshooting section — do not ship an unverified setup. Check #4 catches the \"everything looks green but first message never gets a reply\" failure mode (online connector, registered project, but no role file so session_start rejects). Check #5 catches the \"running service authenticates as connector X while the agent thought it set up connector Y\" split — the .env is authoritative for which row is live, anything else with the agent's user_id is dead weight. Check #6 catches older orphans from prior setup attempts — one machine equals one connector, and duplicates surface in the fleet dropdown as permanently-offline servers users keep clicking."},{"title":"Add architecture.json (strongly recommended)","description":"Do not skip this step. architecture/architecture.json is the single most valuable artifact you will produce during setup. It is an operational snapshot of the project — when Claude (or a human returning after months away) opens a session, the Arch button renders this file and gives them full mental context without reading code. A project without one is a project every new session re-discovers from scratch.

Pick one of the two paths below based on how much the user has ready right now:

Path A — Quick start (≈5 minutes). Use the minimal template below. Fills components, connections, and infrastructure with placeholder values the user can refine later. Good when the user wants to move on to chat and promises to improve the file \"soon\". Set the expectation: this unblocks the Arch button but produces a breadcrumb, not an operational document. Schedule a follow-up to graduate it to Path B within the week.

Path B — Comprehensive (recommended; ≈30-60 minutes). Fetch the full manual first at https://spaiglass.xyz/api/architecture-manual (raw markdown; easy to parse) and read it end-to-end before writing any field. The manual lays out the eight non-negotiable rules — snapshot over design doc, measured status with statusSource, complete site map including orphans, redacted secrets preserving shapes, etc. Then generate the manifest by observing the running system (code at HEAD, running processes, the DB, URLs that actually respond), not by reading README. This is the default path; only fall back to Path A if the user explicitly opts for the quick start.","commands":["mkdir -p ~/projects/myproject/architecture","","# ── Path B: Fetch the manual (READ END-TO-END before writing) ──","curl -fsSL https://spaiglass.xyz/api/architecture-manual -o /tmp/architecture-manual.md","# Manual is ~5 pages of core rules + reference appendix. Do not skim.","","# After reading, generate architecture.json from OBSERVATION:","# git rev-parse HEAD # code as checked out","# systemctl --user list-units # processes actually running","# psql -c '\\d' / mongosh --eval ... # DB as it currently exists","# curl -sSf # routes that actually respond","# du -sh / ls # filesystem as it currently exists","# Write the manifest as a SNAPSHOT, not a design doc.","","# ── Path A: Quick-start minimal template (placeholder only) ──","# Use only if the user explicitly opted out of the comprehensive path."],"example":"{\n \"project\": {\n \"name\": \"MyProject\",\n \"summary\": \"Brief description of what this project does\"\n },\n \"components\": [\n {\n \"id\": \"api\",\n \"name\": \"API Server\",\n \"type\": \"service\",\n \"runsOn\": [\n \"vm1\"\n ],\n \"status\": \"active\",\n \"statusSource\": {\n \"command\": \"systemctl --user is-active myproject-api\",\n \"output\": \"active\",\n \"observedAt\": \"2026-04-20T00:00:00Z\"\n }\n },\n {\n \"id\": \"db\",\n \"name\": \"Database\",\n \"type\": \"datastore\",\n \"runsOn\": [\n \"vm1\"\n ]\n }\n ],\n \"connections\": [\n {\n \"from\": \"api\",\n \"to\": \"db\",\n \"purpose\": \"queries\"\n }\n ],\n \"infrastructure\": [\n {\n \"id\": \"vm1\",\n \"name\": \"Production VM\",\n \"type\": \"vm\"\n }\n ],\n \"architectureRules\": [\n \"All traffic must go through the API gateway\"\n ]\n}","note":"Save at ~/projects/myproject/architecture/architecture.json. The Arch button in the chat UI renders this file; without it, Arch links here. Path A is a placeholder — it unblocks the Arch button but does not substitute for Path B. The manual explains why shallow manifests are worse than no manifest."}],"addMoreVms":"The agent key is reusable. To add another VM, repeat steps 2-4 with the same key — each VM gets its own connector token. Mix and match Linux, macOS, and Windows hosts under the same account.","configuring":{"title":"Configuring SpAIglass (day-2 operations)","summary":"SpAIglass is a browser UI for Claude Code — it does not launch Claude for the user, and it never asks the user about \"absolute paths\" or \"relay vs VM\". When the user says \"rename my server to Foo\" or \"add ~/code/bar to my directory list\", you (the install agent on this VM) make the API call on their behalf. Confirm the plain-English settings you are about to change before firing, then do it. Never instruct the user to reinstall to make a change.","vocab":[{"term":"Server Display Name","scope":"Top-left server name on the chat page, Server dropdown entries, Server segment of the 'last used' buttons, Agent Picker on mobile. Cosmetic — the real connector slug in the URL does not change.","editableBy":"User via Settings wheel OR agent via relay API."},{"term":"Project Directory Display Name","scope":"Top-left project label on the chat page, Directory dropdown entries (shown as ' — '), Agent Picker on mobile. Cosmetic — the real filesystem path does not change.","editableBy":"User via Settings wheel OR agent via VM-local API."},{"term":"Project Directory Tab Name","scope":"Browser tab title (and therefore the text saved when the user bookmarks the page). Falls back to Project Directory Display Name, then to the directory basename. Nothing in-app uses this string.","editableBy":"User via Settings wheel OR agent via VM-local API."},{"term":"Working Directory (real)","scope":"The absolute path on the VM's filesystem, used as Claude Code's cwd for the session. Appears top-left of the chat page alongside the Display Name, and on every Directory dropdown entry. This never changes via a rename — only via unregister + re-register.","editableBy":"Agent only, via register/unregister. No UI path."},{"term":"Connector Slug (real)","scope":"The segment in the URL /vm/./. Stable identity. Changing it invalidates bookmarks and saved 'last used' entries.","editableBy":"Agent only, via installer; never via UI."}],"playbook":[{"userAsks":"\"Rename this server to X\" / \"Change my server name to X\" / \"Call this server X\"","confirmBefore":"Read back: \"I'll change the Server Display Name to X. The URL and bookmarks stay the same. OK to proceed?\"","api":{"method":"PUT","url":"https://spaiglass.xyz/vm//api/__relay/self/display-name","body":"{ \"displayName\": \"X\" }","auth":"Owner-only — must be called from a session that owns the connector. The VM-side agent can curl this with the user's relay cookie or agent key."},"consequences":"Cosmetic. No session history lost. No re-sign-in needed. Dropdown updates on next page refresh.","clearOverride":"Pass { \"displayName\": null } to revert to the raw slug."},{"userAsks":"\"Rename this directory to X\" / \"Call this folder X in the dropdown\"","confirmBefore":"Read back: \"I'll change the Project Directory Display Name for to X. The real path does not change. OK?\"","api":{"method":"PUT","url":"http://127.0.0.1:8080/api/settings/project-display-name","body":"{ \"project\": \"\", \"displayName\": \"X\" }","auth":"VM-local — no auth. Only callable from inside the VM."},"consequences":"Cosmetic. No session history lost. Dropdown + top-left label update on refresh.","clearOverride":"Pass displayName:null to revert to the basename."},{"userAsks":"\"Change the browser tab title to X\" / \"I want the tab to say X when I'm on this project\"","confirmBefore":"Read back: \"I'll change the Project Directory Tab Name for to X. That only affects the browser tab title, nothing else. OK?\"","api":{"method":"PUT","url":"http://127.0.0.1:8080/api/settings/project-directory-tab-name","body":"{ \"project\": \"\", \"tabName\": \"X\" }","auth":"VM-local — no auth."},"consequences":"Cosmetic. Tab title updates on next navigation / refresh.","clearOverride":"Pass tabName:null to fall back to the Display Name (and then to the basename)."},{"userAsks":"\"Add to my dropdown\" / \"Put ~/code/foo in the picker\"","confirmBefore":"Read back: \"I'll add to your Directory dropdown. It'll show up with the label '' unless you want a different Display Name. OK?\" If the path does not exist yet, say so — do not silently create a stray directory far from where the user meant.","api":{"method":"POST","url":"http://127.0.0.1:8080/api/projects/register","body":"{ \"name\": \"\" } // or { \"name\":\"foo\", \"path\":\"/home/user/code/foo\" } for an explicit path\n// role is optional; include { \"role\": \"\" } only if the user asked for a persona","auth":"VM-local — no auth."},"consequences":"No session history touched. Dropdown updates on next page refresh. If a hidden entry for the same path existed before, prior session transcripts under ~/.claude/projects// are restored automatically."},{"userAsks":"\"Hide \" / \"Remove from the dropdown\" / \"I don't want to see in the picker\"","confirmBefore":"Read back: \"I'll remove from your Directory dropdown. Session transcripts stay on disk, so if you change your mind later I can re-add it and your history comes back. OK?\"","api":{"method":"POST","url":"http://127.0.0.1:8080/api/projects/unregister","body":"{ \"path\": \"\" }","auth":"VM-local — no auth."},"consequences":"Dropdown entry disappears on next page refresh. Session transcripts under ~/.claude/projects// are preserved. Idempotent: removing an already-removed path returns removed:false."},{"userAsks":"\"What's in my Directory dropdown?\" / \"List my directories\" / \"Show me my registered paths\"","confirmBefore":"Read-only. No confirmation needed.","api":{"method":"GET","url":"http://127.0.0.1:8080/api/projects","body":"(none)","auth":"VM-local — no auth."},"consequences":"Returns { projects: [{ path, encodedName }] }. The path is the real filesystem directory; the dropdown shows it with any Display Name override applied on top."},{"userAsks":"\"What Project Directory Display Names are set?\" / \"Which directories have custom names?\"","confirmBefore":"Read-only. No confirmation needed.","api":{"method":"GET","url":"http://127.0.0.1:8080/api/settings/project-display-names","body":"(none)","auth":"VM-local — no auth."},"consequences":"Returns { displayNames: { '': '