Configuration
The agent's entire local footprint is one TOML file: a server URL, a token reference, a project, and a list of model_code → command bindings. Everything else is brain-side — methodology, buckets, passes, categories, fingerprint/dedupe config, all state.
Locate the config file
Path resolution order:
--config <path>flagTHESPIDER_CONFIGenv var~/.thespider/config.toml
Write a minimal config
server = "https://thespider.xyz" # required. On-prem: your instance URL. Only mode coupling.
token = "keychain:thespider" # optional; see "Token storage"
project = "shipstream/thespider" # optional; else the token's single project is used
concurrency = 2 # optional; parallel model runs (default 1)
[[model]]
code = "sonnet" # must match a server-side GET /v1/models code
command = "bash runners/opencode-runner.sh {prompt_path} anthropic/claude-sonnet-4-6"
timeout_seconds = 900 # optional; falls back to the lease's advisory timeout
[[model]]
code = "claude-cli"
command = "claude --print < {prompt_path}"
server, token, project, concurrency) before the first [[model]] block, otherwise a trailing concurrency = 2 is parsed as a field of the last model, not the root.Resolve the project
project accepts:
org-slug/project-slug- a bare project slug
- a numeric id
If omitted, the token's single project is used.
Substitute command variables
Each model command is a template. These variables are substituted and POSIX-single-quoted:
| Variable | Value |
|---|---|
{prompt_path} | absolute path to the rendered prompt written to a private temp file |
{target_path} | the repo checkout root (--target-path, else the git top-level, else cwd) |
{model_code} | the slice's model code |
{slice_id} | the slice id |
Rules:
- An unknown
{variable}is a hard error naming the variable. ({thespider_dir}/{workspace_path}from the legacy CLI do not exist here.) - A
{...}that is not a valid identifier (e.g.{},{1x},{a-b}) is left literal.
Store the token
login stores the enrolled token in the OS keychain (keyring) when a keychain service is available, otherwise in a 0600 token file next to the config (<config-dir>/token) — the headless-Linux / CI path. Resolution follows the config token reference:
token value | behaviour |
|---|---|
(omitted) / keychain | keychain service thespider, else the token file |
keychain:<service> | that keychain service, else the token file |
env:THESPIDER_TOKEN | read from the named environment variable |
<literal token> | used verbatim (nothing for login to manage) |
Set THESPIDER_NO_KEYCHAIN=1 to force the token-file fallback — deterministic on headless hosts. The keychain "account" is the server URL, so multiple servers can share one keychain service.
Author methodology in the web UI
Buckets, passes, categories, and prompt sections are server-authored and versioned (config_versions). Each save becomes a new immutable version; campaigns pin the version they started with, so in-flight work renders from the methodology it began with. On-prem instances pull methodology updates from the mothership using the license JWT as auth, and every image release bundles a snapshot for air-gapped installs.
The default project is campaign-ready at first boot — the image bundles a default methodology snapshot seeded as config_version 1 with the sonnet model enabled.
Next steps
- Run the agent — every
thespider-agentcommand. - Environment reference — server-side knobs.