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
Automation time windows The Time of Day / Day of Week trigger filter lets an automation fire only
when the event happens inside (or outside) a set of time windows. It sits next
to the other trigger filters — channel, role, cCommand access Every command has a Permission Level (Everyone, Administrators, Moderators,
Server Managers, or custom permissions). Under it, in the same Permissions section
of the command's page, are role rules:Command sync Nobody has to run register-commands. A server's slash commands reach Discord
by themselves, and a deploy that changes a command reaches every server.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 moGame — the hidden-agent round A round for everyone in a voice channel. All but one player are told a secret
word; one is the agent and is not. They talk in voice, anyone can call a
vote, and the table ejects who it thinks the agenMember content /about lets chosen members keep one short piece of content about themselves.
The bot serves it back, and so does one read-only API route.Member Rooms Member rooms let ordinary members create and run their own Discord channels —
text or voice — that clean themselves up afterwards. A server admin defines a
preset; members create rooms from it, and eaObservances — a historical day, posted as it happened A server owner can turn on a timeline: the events of a historical day,
posted one at a time as their minutes come round on the anniversary. 8:46 AM
arrives at 8:46 AM.Oldest /oldest answers "who has been on Discord the longest?" with a top ten.Plan: 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.Quorum — decisions that close themselves /quorum puts a yes/no question to a server with one command. The question
closes itself at a deadline, posts a RESULT card naming an owner and a due
date, and nudges that owner once when the date arriSecrets 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 MThe /help command /help answers one question: what can I run here?The SpaceBot Activity SpaceBot runs inside Discord as an Activity: a panel opened from a voice
channel's Activities menu, or from a direct message, that shows live SpaceBot
state to the people in it. It is one Activity witTimebox /timebox runs focus blocks and breaks, alone or for everyone in a voice
channel. The default is one block of 23 minutes of focus and then it is done. Ask for
more rounds and it adds a 5-minute break aVoice channel threshold trigger The Voice channel reached a head-count trigger (VOICECHANNELTHRESHOLD)
fires once when a voice channel's member count first reaches N. Example: "when
4 people are in General Voice, post the gang's all