Developer Documentation
How SpaceBot is built and operated — the runtimes, the REST API, the local runner, the workflow engine, and integrations. Sourced from the repo’s docs/ folder.
Start here
Architecture SpaceBot is not a single process. The same repository produces code for
several cooperating runtimes that share one Cloudflare D1 (SQLite) database. A
file's location determines which runtime it runs SpaceBot API The stable external API lives under /api/v1/ and uses Authorization: Bearer sblive... API keys.SpaceBot Integration Protocol This guide explains how external projects can integrate with SpaceBot to provide Discord slash commands, receive lifecycle events, and maintain a live connection.
Features & subsystems
AI Autopilot (Workflows + Queues Foundation) This document describes the initial implementation for durable DM AI execution with retries, recovery, and timeline visibility.Local Runner V2 (Typed Jobs) This document covers the typed local-runner capabilities added for cross-platform host automation.Superadmin Workflows The superadmin workflow system replaces the hardcoded gateway cron jobs with
D1-defined workflow templates that are editable in the builder UI
(Admin → Superadmin → Workflows), scheduled with real croPublic Server Browser A public directory of Discord communities running SpaceBot, at
/servers(https://spacebot.starspace.group/servers). Server administrators opt in from
their dashboard; nothing is published automatically
Operations
Observability Set SENTRYDSN to enable Sentry for client and server runtime errors. Optional values:Data Retention Long-term history is kept as aggregates, which are tiny; the raw event
firehose underneath them is pruned. This is what lets trends survive
indefinitely without the row counts that caused the D1 blowoAlerting Configure project alerts for new issues, error-rate spikes, and transaction latency regressions after SENTRYDSN is set.HTTP/3 on Cloudflare HTTP/3 is a Cloudflare zone-level setting, not SvelteKit application code.Asset Optimization Source PNG/JPG assets are kept when they are canonical screenshots or icons. Optimized WebP variants should be used by app surfaces where available.
Guides
More
Durable message purge Delete actions that sweep a user's message history across every channel —
DELETEUSERMESSAGES, DELETEMESSAGES, DELETEMENTIONEDMESSAGES, the kind
of thing a /spam moderation command runs — can be far moPlan: SpaceBot as an interface to Dirac Status: plan, not implemented (2026-07-12). Goalposts, David's words: the local
runner connects into the Dirac Claude system ("I tell it where to look, and it
should kinda find it on its own"), then SQuerying production bun run db:query runs a read-only query against the production D1 database
(spacebot-logs). It exists so that "why didn't that fire?" can be answered by
looking, instead of guessed at from the source.Secrets src/lib/secrets.ts reads GCP Secret Manager and falls back to environment
variables. On the production VM the fallback is the only path that has ever
run. Two things independently prevent the Secret M