Quickstart
This quickstart runs a full audit against a local repo using a deterministic fake model, then checks the gate. It assumes you have installed the server and built the agent.
Start the server
cd server && bun install
docker compose up -d && bun run migrate && bun run serve
Mint an enrollment code
Enrollment codes are single-use and short-lived. Mint one for the default project:
bun run src/mint-enrollment-code.ts --org default --project default
# copy the printed `code:` value
Point the agent at the server
Create ~/.thespider/config.toml. For local dev use the deterministic fake-model.ts so you don't need real model credentials:
server = "http://localhost:8080"
token = "keychain:thespider"
project = "default"
[[model]]
code = "sonnet"
command = "bun run ../fake-model.ts {prompt_path}"
timeout_seconds = 120
server, token, project, concurrency) before the first [[model]] block, or a trailing key is silently parsed as a field of the last model.Enroll the agent
echo "<code>" | thespider-agent login
login opens <server>/activate, reads the enrollment code from stdin, and stores the client token in the OS keychain (or a 0600 token file on headless hosts).
Run the audit
cd /path/to/your/repo
thespider-agent run --once
run --once claims a batch of slices, writes each prompt to a temp file, spawns the model command via sh -c, heartbeats the lease, and POSTs the raw stdout to /v1/leases/{id}/results.
Check the gate
thespider-agent gate --campaign <id>
# exit 0 = pass, 1 = fail (new findings), 2 = pending
View findings in the web UI
Open http://localhost:8080/ — findings are parsed, fingerprinted, deduped, and ready to triage. Project-level identity means statuses you set on main carry over to PR branches.
Next steps
- Configure the agent — every
config.tomloption. - Campaigns — full, incremental, and retest semantics.
- PR gate — wire up the forge webhook + daemon pattern.