AI is optional
SpiderCaster builds every page offline unless you set up an AI provider. With no provider, it runs no model, sends nothing out, and records zero tokens. TokenCTR is SpiderCaster's optional token service: free paths stay the default, and paid credits are spent only if you opt in.
How the AI path works
AI helps plan and patch sections from your own words. The same never-invent rule applies: the planner is told to use only facts from your copy.
Off by default
A build without --offline and with no provider set falls back to the offline build and says so in a warning line.
Stop instead
Add --no-fallback and the build stops with an error when no provider is set, instead of falling back.
Free models first
The chain tries free Gemini models, then free OpenRouter models, then an OpenWork endpoint.
Paid only when allowed
Paid OpenRouter models join the chain only with --allow-paid.
A ledger for every run
report.json records the provider, the model, the requests, the tokens in and out, and an estimated cost.
Turn it on
Providers are set with environment variables. SpiderCaster reads keys by name and never writes them into a site.
Gemini
Set GEMINI_API_KEY with a free key from Google AI Studio.
OpenRouter
Set OPENROUTER_API_KEY. Models whose names end in :free are booked at zero cost.
OpenWork
Set OPENWORK_INFERENCE_BASE_URL and OPENWORK_API_KEY for an endpoint that your organisation provides.
No-key chain
Set SC_AI=on to add the no-key free chain. It is off by default and does not show in the models list in 0.1.0.
See the chain
python spidercaster.py models lists each provider, whether it is set up, and its default models.
With no provider set
The provider list, a build that falls back to offline, and the same build with --no-fallback.
$ python spidercaster.py models
provider chain (free tiers first; paid only with --allow-paid):
gemini not configured Google Gemini (AI Studio free tier / Vertex express)
models: gemini-2.5-flash-lite, gemini-2.0-flash, gemini-2.5-flash
openrouter not configured OpenRouter
models: meta-llama/llama-3.3-70b-instruct:free, deepseek/deepseek-chat-v3-0324:free, google/gemini-2.0-flash-exp:free, qwen/qwen-2.5-72b-instruct:free
openwork not configured OpenWork inference (org-provided)
models: (no models set)Exit code: 0
$ python spidercaster.py build projects/my-site --out sites/ai-try
[warn] AI build failed -> offline fallback (no AI provider configured; set GEMINI_API_KEY (free tier) or OPENROUTER_API_KEY, or run with --offline for a zero-token build)
built sites/ai-try (mode: offline-fallback)
pages: index.html, favicon.svg
tokens: requests=0 ok=0 in=0 out=0 est_cost=$0.0000
index: NOINDEX (default; pass --indexable to flip)
robots: sites/ai-try/robots.txt
next: python spidercaster.py check sites/ai-try
python spidercaster.py serve sites/ai-tryExit code: 0
$ python spidercaster.py build projects/my-site --no-fallback --out sites/ai-try2
no AI provider configured; set GEMINI_API_KEY (free tier) or OPENROUTER_API_KEY, or run with --offline for a zero-token buildExit code: 1
Where AI is used
Two commands can call a model, and both have a zero-token path.
build
Plans the whole site from your words. With --offline it uses the rule-based planner instead, at zero tokens.
refine
Patches one section of a built site at a small token cost. With --offline it changes the theme only, at zero tokens.
Preview first
--dry-run on build or refine shows the planned change at zero tokens and writes nothing.
TokenCTR, the optional token service
Version 0.1.0 ships without the TokenCTR provider. SC AI Chain's TokenCTR provider is coming in the next release, and this is how it is built to work.
Free by default
With nothing set, builds stay on the offline build and the free routes. A build never creates a TokenCTR key on its own.
Paid only if you opt in
TokenCTR joins only when TOKENCTR_API_KEY is set and SC_TOKENCTR_PAID=1 is set, and then only with --provider tokenctr or --allow-paid.
Your own credits
Calls go through the TokenCTR gateway at api.tokenctr.com and draw on credits you bought.
Honest costs
The ledger marks every call free or paid. A cost it cannot measure is logged as unknown, never as $0.
An empty balance
When credits run out, the build falls back to the no-key chain if SC_AI=on is set, or to the offline build.
Until the next release
In 0.1.0 the OpenWork slot accepts any endpoint that speaks the same chat format, and the ledger books its cost as zero, so read real spend on your provider's own usage page. Prices for TokenCTR credits are set by TokenCTR, not by SpiderCaster.