SpaceBot 🚀
A powerful, self-hosted Discord bot platform built with SvelteKit 2
(Svelte 5) and deployed on Cloudflare Pages. Create custom slash commands,
build event-driven automations, and monitor all Discord activity through a
beautiful admin dashboard.
✨ Features
🤖 Discord Bot
- Custom Slash Commands — Create your own commands with parameters, choices,
and custom responses
- Event-Driven Automations — Trigger actions automatically when Discord
events occur
- Full Gateway Support — Real-time event capture via Discord.js gateway
connection
- Interactions Endpoint — HTTP-based slash command handling via Cloudflare
Workers
- Member Rooms — Members create and run their own text or voice channels with
/room or a join-to-create lobby; a server preset decides who may make one, what
the creator can do to it, and when it closes itself
- Timebox —
/timebox start runs focus blocks and breaks (23/5/15 minutes by default),
alone or for everyone in your voice channel, with Pause / Skip / Stop and an optional
"deafen me" you can always lift. Off until a server enables it (see
docs/timebox.md)
- Activity — SpaceBot as a Discord Activity, opened from a voice channel or a DM,
with a tab per module. The foundation is built (sign-in, place check, module
switch); the timebox is its first module (see docs/activity.md)
- Quorum —
/quorum ask puts a yes/no question to the server; it closes itself
at the deadline, posts a RESULT naming an owner and a due date, and keeps counts
only, never who voted (see docs/quorum.md)
- Observances — Post a historical day's events at the minutes they happened,
on its anniversary. Ships with September 11, 2001; off unless a server owner
turns it on and picks a channel (see docs/observances.md)
- Context Menu Commands — Message context menu registration and routing with
server-side permission enforcement
- AI Chat for Managers — Server managers can DM the bot for AI-powered
assistance. In production this runs on Cloudflare Workers AI (optionally
through an AI Gateway for analytics/caching); in local development you can
point it at an Ollama model instead (
AI_PROVIDER=ollama, default gemma3:4b).
- AI DM Autopilot — When enabled, gateway DMs are enqueued onto a Cloudflare
Queue and handled by a standalone orchestrator worker (see
docs/ai-autopilot.md).
🌐 Web Dashboard
- Server Selection — Manage all servers where you're an admin
- Event Logs — View detailed logs of all Discord activity (members,
messages, voice, moderation, etc.)
- Automation Builder — Visual interface to create event → action automations
- Command Builder — Design custom slash commands with the automation action
system
- Public Server Browser — An opt-in directory at
/servers where admins can publish
their community (off by default; see Server Browser)
- Dark/Light Theme — Beautiful UI with theme toggle support
- Operational UX — Global toasts, skeleton loading states, route-level error
handling, and reduced-motion-aware transitions
🧩 Automation & Extensibility
- Local Runner — A standalone Bun CLI users install on their own machine. It
connects to the server over WebSocket, runs jobs as shell commands inside a
path allowlist, and streams results back (see
docs/local-runner-v2.md).
- Superadmin Workflows — Scheduled, server-spanning workflow templates driven
by
cron_expression values stored in D1 (see
docs/superadmin-workflows.md).
- MCP Server — A standalone Model Context Protocol server (
mcp-server/) that
exposes SpaceBot data/operations to MCP-aware clients.
🔐 Authentication & Security
- Discord OAuth2 — Secure login with Discord credentials
- Sliding Session TTL — Configurable cookie lifetime via
SESSION_TTL_SECONDS
- Token Refresh — Page navigations renew the Discord access token from the
stored refresh token; a session that can't be renewed is cleared rather than
left half-authenticated
- Admin Access Control — Only server admins can manage their servers
- Request Signature Verification — All Discord interactions are
cryptographically verified
- Browser Hardening — Same-origin checks for cookie-authenticated JSON
mutations plus HTML security headers and report-only CSP
⚡ Cloudflare-Native
- Cloudflare Pages — Deployed on Cloudflare's global edge network
- D1 Database — SQLite-based serverless database for logs and configurations
- Workers AI — AI-powered DM responses via Cloudflare's free LLM models
- AI Gateway — Optional analytics, caching, and rate limiting for AI requests
- Zero Cold Starts — Fast response times worldwide
Roadmap Operations
Repository-ready external integrations are configured with environment variables, not hardcoded credentials:
PUBLIC_SUPPORT_DISCORD_URL, PUBLIC_BOT_VOTE_URL, and PUBLIC_BOT_REVIEW_URL power public community CTAs.SENTRY_DSN, SENTRY_ENVIRONMENT, and SENTRY_TRACES_SAMPLE_RATE enable Sentry.RATE_LIMIT_ENABLED, RATE_LIMIT_DEFAULT_WINDOW_SECONDS, and RATE_LIMIT_DEFAULT_MAX_REQUESTS enable D1-backed API limits.
Useful checks:
bun run docs:api
bun run audit:deps
bun run images:check
bun run verify:http3
📸 Screenshots
Secure Discord OAuth2 authentication for accessing the admin dashboard.
View event logs, statistics, and quick access to automations and commands.
The dashboard also supports a clean light theme.
Create event-driven automations that trigger on Discord events like member
joins, message creates, voice state changes, and more.
Visual interface for configuring triggers, conditions, and actions for your
automations.
Build custom slash commands with parameters and tie them to automation actions.
Design slash commands with options, parameters, and custom responses through an
intuitive editor.
Comprehensive logging of all Discord events with filtering and search.
🛠️ Tech Stack
| Layer | Technology |
|---|
| Framework | SvelteKit 2 (Svelte 5) |
| Edge runtime | Cloudflare Pages/Workers |
| Package manager | Bun |
| Database | Cloudflare D1 (SQLite) |
| Bot Library | Discord.js 14 |
| AI | Cloudflare Workers AI / AI Gateway (prod); Ollama (dev only) |
| Styling | Custom CSS with CSS Variables |
| Auth | Discord OAuth2 |
🚀 Getting Started
Prerequisites
- Bun 1.3+ (the project's package manager and runtime — used for
every script; Node.js is not required)
- A Discord Application
(create one here)
- A Cloudflare account (sign up here)
- (Optional)
cloudflared
for local tunneling
Installation
-
Clone the repository
git clone https://github.com/starspacegroup/spacebot.git
cd spacebot
-
Install dependencies
bun install
-
Configure environment variables
Copy .env.example to .env and fill in your Discord credentials:
cp .env.example .env
Required variables:
| Variable | Description |
|---|
DISCORD_PUBLIC_KEY | Found in your app's "General Information" |
DISCORD_CLIENT_ID | Your application's Client ID |
DISCORD_CLIENT_SECRET | Found under OAuth2 settings |
DISCORD_BOT_TOKEN | Found under "Bot" settings |
ADMIN_USER_IDS | Comma-separated Discord user IDs with global admin access |
LOG_LEVEL | Logging verbosity: error, warn, info, debug |
Optional AI variables (for DM chat functionality):
| Variable | Description |
|---|
CLOUDFLARE_ACCOUNT_ID | Your Cloudflare account ID |
CLOUDFLARE_AI_TOKEN | API token with Workers AI permissions |
CLOUDFLARE_AI_GATEWAY_ID | (Optional) AI Gateway ID for analytics/caching |
CLOUDFLARE_AI_MODEL | (Optional) Override default LLM model |
-
Set up the database (local development)
bun run db:migrate:local
-
Run the development server
bun run dev
The app will be available at http://localhost:4269 (the port is pinned in
vite.config.js).
-
Start the Gateway bot (in a separate terminal)
Discord Bot Setup
- Go to Discord Developer Portal
- Select your application → Bot
- Enable Privileged Gateway Intents:
- ✅ Presence Intent
- ✅ Server Members Intent
- ✅ Message Content Intent
- Go to OAuth2 → URL Generator
- Scopes:
bot, applications.commands
- Permissions: Administrator (or customize as needed)
- Use the generated URL to invite the bot to your server
Setting up Interactions Endpoint
For production, configure Discord to send interactions to your Cloudflare Pages
URL:
- Deploy to Cloudflare Pages (see Deployment)
- Go to Discord Developer Portal → Your Application → General Information
- Set Interactions Endpoint URL to:
https://your-domain.pages.dev/api/discord/interactions
📦 Available Bun Scripts
| Script | Description |
|---|
bun run dev | Start SvelteKit dev server |
bun run dev:wrangler | Run with Wrangler (Cloudflare local environment) |
bun run dev:gateway | Start Discord gateway bot |
bun run dev:tunnel | Start cloudflared tunnel for local development |
bun run build | Build for production |
bun run db:migrate | Run database migrations (production) |
bun run db:migrate:local | Run database migrations (local) |
bun run register-commands | Register slash commands with Discord |
bun run test | Run the Vitest test suite |
bun run test:e2e | Run the Playwright smoke suite |
bun run typecheck | Type-check with svelte-check |
bun run lint | Run ESLint |
bun run runner | Start the local runner CLI |
🔄 Automations
SpaceBot's automation engine lets you create powerful event-driven workflows:
Supported Triggers
- Member Events — Join, leave, ban, unban, kick, timeout
- Message Events — Create, edit, delete, bulk delete
- Voice Events — Join, leave, mute, deafen, stream, video
- Role Events — Create, delete, update, member role add/remove
- Channel Events — Create, delete, update
- Reaction Events — Add, remove
- Interaction Events — Slash commands, button clicks, modals
- And many more...
Available Actions
- 📨 Send Message — Send a message to a channel
- 🗑️ Delete Messages — Delete messages from a user
- 🗑️ Delete Messages Mentioning User — Delete messages that mention a specific user
- 🏷️ Add/Remove Role — Modify member roles
- 👢 Kick Member — Kick a member from the server
- 🔨 Ban Member — Ban a member
- ⏰ Timeout Member — Timeout a member
- 📢 Send DM — Send a direct message to a user
Template Variables
Use dynamic variables in your messages:
Welcome {user.mention} to {guild.name}!
Available: {user.id}, {user.name}, {user.mention}, {channel.name},
{guild.name}, {option.<name>}, and more.
🎮 Custom Commands
Create custom slash commands through the web dashboard:
- Navigate to Admin → Your Server → Commands
- Click New Command
- Configure:
- Command name and description
- Parameters (text, numbers, users, channels, roles, etc.)
- Response message or embed
- Optional: Tie to an automation action
- Click Register with Discord to sync
📋 Event Logging
SpaceBot captures and logs all Discord events:
| Category | Events |
|---|
| 👤 Member | Join, leave, update, nickname changes |
| 💬 Message | Create, edit, delete, bulk delete |
| 🎤 Voice | Join, leave, mute, deafen, stream, video |
| 📁 Channel | Create, delete, update |
| 🏷️ Role | Create, delete, update, member assignments |
| 🔨 Moderation | Ban, unban, kick, timeout |
| ⚡ Interaction | Commands, buttons, modals, select menus |
| 📅 Events | Scheduled event create, update, delete |
🌐 Deployment
Deploy to Cloudflare Pages (Recommended)
-
Push to GitHub
git push origin main
-
Connect to Cloudflare Pages
- Go to Cloudflare Dashboard
- Workers & Pages → Create application → Pages → Connect to
Git
- Select your repository
- Configure:
- Build command:
bun run build
- Build output:
.svelte-kit/cloudflare
-
Add Environment Variables In Cloudflare Pages Settings → Environment
Variables, add all required variables.
-
Create D1 Database
wrangler d1 create spacebot-logs
Update wrangler.toml with the database ID.
-
Run Migrations
bun run db:migrate
-
Deploy Future pushes to main will auto-deploy.
AI queue orchestration also auto-deploys via GitHub Actions in .github/workflows/deploy-orchestrator-worker.yml.
Configure these repository secrets so worker deploys can run:
CLOUDFLARE_API_TOKENCLOUDFLARE_ACCOUNT_IDORCHESTRATOR_SPACEBOT_API_BASEAI_AUTOPILOT_INTERNAL_KEY
See DEPLOYMENT.md for detailed instructions.
📁 Project Structure
spacebot/
├── src/
│ ├── lib/
│ │ ├── ai/ # AI chat, MCP client, retry policy
│ │ ├── automation/ # Event → action automation engine
│ │ ├── components/ # Svelte components
│ │ ├── db/ # D1/SQLite access, one module per domain
│ │ ├── discord/ # Gateway client, REST, bot registry, commands
│ │ ├── integrations/ # External integrations (e.g. GitHub) + auth
│ │ ├── server/ # Server-only helpers (cron, workflow runtime)
│ │ └── utils/ # Shared utilities
│ ├── routes/
│ │ ├── admin/ # Per-server dashboard (under [serverId]/)
│ │ ├── account/ # User-level AI jobs / workflows / operations
│ │ └── api/ # REST endpoints (+ api/v1, api/runner/ws)
│ ├── tests/ # Vitest test suites
│ └── hooks.server.ts # Edge auth + request handling
├── orchestrator-worker/ # Cloudflare Queue consumer (AI autopilot, cron)
├── mcp-server/ # Standalone MCP server
├── scripts/ # CLIs and tooling (incl. scripts/local-runner/)
├── migrations/ # D1 database migrations (immutable once applied)
├── _functions/ # Cloudflare Pages Functions
├── static/ # Static assets
└── docs/ # Documentation (incl. architecture.md, screenshots/)
See docs/architecture.md for a diagram of how the runtimes
fit together, and CLAUDE.md for the authoritative architecture notes.
📚 Documentation
Developer documentation is served on the main site at
https://spacebot.starspace.group/docs/dev — rendered at build time from
docs/, so there's no separate docs host to maintain.
Highlights: Architecture · API ·
Integrations · AI Autopilot ·
Local Runner v2 · Superadmin Workflows ·
Server Browser ·
Observability · Tutorials.
🔒 Security
- ✅ Discord request signature verification
- ✅ Same-origin checks for cookie-authenticated JSON mutations
- ✅ Security headers and report-only CSP for HTML responses
- ✅ HTTP-only secure cookies
- ✅ Configurable sliding session TTL
- ✅ Admin permission checks
- ✅ Environment variable secrets
- ✅ HTTPS via Cloudflare
🗺️ Roadmap
See ROADMAP.md for planned features and enhancements.
🤝 Contributing
See CONTRIBUTING.md for local setup, the project's hard rules
(immutable migrations, Bun-only, the multi-runtime model), and how to run tests
before opening a PR.
📄 License
MIT
🔗 Resources
