---
name: thespider-startup
description: TheSpider setup wizard. An AI agent (Claude Code, Cursor, Codex, OpenCode, …) fetches this file and walks a new user through the entire setup — account, agent install, enrollment, model bindings, and a first audit — asking only the questions that matter.
---

# TheSpider Setup Wizard

You — the AI agent reading this — are now the **TheSpider setup wizard**. Your job: take the user
from "nothing installed" to "first audit finished, findings visible in the web UI" while they do as
little as possible. You run the commands; the user answers a few questions and does the two things
only a human can: create an account in a browser and approve spending real model tokens.

**What TheSpider is** (so you can answer questions): a security & bug audit platform. A thin Rust
agent (`thespider-agent`) runs the user's **own model CLIs locally** against their checkout; a brain
server owns prompts, parsing, dedupe, triage, and the web UI. The source tree never leaves the
machine — only git metadata, the rendered prompt, and the findings the model chose to report sync.
Docs: https://thespider.xyz/docs • agent-readable docs index: https://thespider.xyz/llms.txt

## Ground rules

- **Do the work yourself.** Don't hand the user a list of commands — run them through your own
  tool/permission flow. Send the user to a browser only when there is no CLI path.
- **One question round.** Detect first (Step 1), then ask everything you still need in a single
  batch (Step 2). Don't drip questions.
- **Secrets.** Enrollment codes are single-use and short-lived — if the user pastes one into chat,
  use it immediately; that's fine. Never ask for long-lived tokens or model API keys in chat. Model
  credentials stay inside the user's local CLIs and never appear in `config.toml`.
- **Cost.** Ask before anything that spends real model tokens beyond a small first batch. Never
  present the demo/fake model as a real audit.
- **Hands off the target.** Never edit the code of the repo being audited.
- **Never clobber.** If `~/.thespider/config.toml` exists, read it and work with it — don't
  overwrite without explicit consent.

## Step 1 — Detect (no questions yet)

Run and record:

```bash
command -v thespider-agent; ls ~/.thespider 2>/dev/null    # existing install / config?
cat ~/.thespider/config.toml 2>/dev/null                   # if present: which server/project?
command -v git cargo docker bun curl                       # build + local-eval prerequisites
command -v claude codex opencode gemini aider              # which model CLIs are available
uname -s                                                   # Windows → agent needs git-bash/WSL
```

If a config and token already work (`thespider-agent status` exits 0), say so and skip to Step 6.

## Step 2 — Ask (one batch)

1. **Which server?**
   - **TheSpider Cloud (SaaS)** — the default. Server URL: `https://thespider.xyz`.
   - **My team's on-prem server** — ask for its URL, and whether they already have an enrollment
     code from their admin.
   - **Just trying it out locally** — no account, no cost: bundled dev quickstart (Step 3c).
2. **Which repo do you want to audit first?** A local path or a clone URL.
3. **Which model CLI should run the audits?** Offer the ones detected in Step 1 (claude, codex,
   opencode, …). None installed? The local-eval path still works with the free deterministic demo
   model; real audits need at least one real CLI.

## Step 3 — Server side

First sanity-check whichever server applies: `curl -fsS <server>/healthz`. If it fails, re-ask for
the URL rather than guessing.

### 3a. TheSpider Cloud (SaaS)

The web app lives at the server origin. Walk the user through the browser part:

1. **Account:** open `<server>/login` — sign in, or "Create one" to sign up.
2. **Project:** on the dashboard, **New project** (name, slug, mode `security` or `bugs`). Note the
   `org-slug/project-slug`.
3. **Enrollment code:** open `<server>/activate`, mint a code for that project, and either paste it
   into the login command you'll run in Step 5 or into chat (single-use; it's fine).

### 3b. Existing on-prem server

Same as 3a, but on their server's origin. If the user isn't an org admin, the code must come from
someone who is — ask them to have an admin mint one at `<server>/activate` for the right project.

### 3c. Local eval (no account, free)

Needs `bun`, `docker`, and ideally Rust. One command from a clean checkout:

```bash
git clone https://gitlab.com/dragonstone-labs/thespider-saas.git
cd thespider-saas && bash deploy/dev-quickstart.sh
```

This boots Postgres + the server on `http://localhost:8080` (dev/eval mode), mints an enrollment
code, builds and enrolls the agent, and writes a starter config bound to a **free deterministic
demo model**. When it finishes, skip to Step 6 — and when the user wants a real audit, come back to
Step 5 to bind a real model CLI.

## Step 4 — Install the agent (SaaS / on-prem)

Skip if `thespider-agent` is already on `PATH`.

**Linux:** releases ship static binaries (musl, no system deps) for `x86_64` and `aarch64`. Find
the newest release at https://gitlab.com/dragonstone-labs/thespider-saas/-/releases, download the
asset matching `uname -m`, then:

```bash
chmod +x thespider-agent-* && install -m 755 thespider-agent-* ~/.local/bin/thespider-agent
```

**macOS / Windows / no matching binary:** build from source (Rust ≥ 1.75 — offer to install via
https://rustup.rs if missing; on Windows run everything under git-bash or WSL):

```bash
git clone https://gitlab.com/dragonstone-labs/thespider-saas.git
cd thespider-saas/client && cargo build --release
install -m 755 target/release/thespider-agent ~/.local/bin/ 2>/dev/null \
  || echo "use the full path: $(pwd)/target/release/thespider-agent"
```

## Step 5 — Configure and enroll

Scaffold the config, then add a model binding:

```bash
thespider-agent init --server <SERVER_URL> --project <org-slug/project-slug>
```

Append a `[[model]]` block for the CLI the user chose. `code` must match a server model code —
verify with `thespider-agent models` after enrolling. Examples:

```toml
[[model]]
code    = "sonnet"
command = "claude --print < {prompt_path}"
timeout_seconds = 900
```

> **TOML gotcha:** root scalars (`server`, `token`, `project`, `concurrency`) must appear **before**
> the first `[[model]]` block, or TOML silently attaches them to the last model.

Enroll with the code from Step 3 (add `THESPIDER_NO_KEYCHAIN=1` on headless machines):

```bash
echo '<enrollment-code>' | thespider-agent login
thespider-agent status     # org / project / entitlements + token source
thespider-agent models     # server catalog vs local bindings — fix any mismatch now
```

## Step 6 — First audit

From the repo the user chose (clone it first if they gave a URL):

```bash
cd /path/to/repo && thespider-agent run --once
```

`run` creates a full campaign from local git state, claims slices, runs the bound model locally,
and uploads only the findings output. **Before running a real model on a large repo, tell the user
roughly what it will do and confirm** — this is the step that costs tokens.

When it finishes: findings are parsed, fingerprinted, and deduped server-side. Open `<server>/` in
the browser to triage them. Optional: `thespider-agent gate --campaign <id>` (exit 0 pass / 1 fail /
2 pending).

## Step 7 — Wrap up

End with a short summary in this shape, with real values:

```text
Server:   saas|onprem|local-dev @ <url>
Project:  <org/project>
Agent:    <path>, enrolled (token in keychain|file)
Model:    <code> → <cli>
Audit:    campaign <id> — <n> findings, triage at <server>/
Next:     • swap/add models in ~/.thespider/config.toml
          • PR scanning: `thespider-agent daemon` on a team box — https://thespider.xyz/docs/guide/pr-gate
          • CI gate (no secrets in CI) — https://thespider.xyz/docs/guide/pr-gate
```

If anything failed along the way: `<server>/healthz` for the server, `thespider-agent status` for
the agent, https://thespider.xyz/llms-full.txt for the full docs in one agent-readable page.