Documentation
AlterOS is the middleman between server owners and their admins. Every channel, role, and permission change goes through your approval first.
Getting started
1. Login with Discord
Landing page, Login with Discord. We request identify guilds. No separate account.
2. Invite the bot
Dashboard, your server, Invite bot. Needs Manage Channels Manage Roles. Move bot role to top of Server Settings, Roles otherwise Replace mode cannot delete/manage high roles.
3. Pick a server
Switch server via TopBar guild switcher. Owner-only templates verified by user_id on every CRUD.
Onboarding & aesthetics
When you create a template (/templates/new) you choose Start empty vs Guided setup (equal prominence). Guided is a 5-step wizard that generates a starter.
Steps
- Purpose: gaming, community, study, creator, business, support
- Size + moderation: small/medium/large + relaxed/balanced/strict (strict adds slow-chat, reports, staff-voice)
- Extras: voice, events
- Aesthetic: channels + roles (see below)
- Preview: edit before Save
Aesthetics researched
10 channel styles and 6 role styles from top Discord servers:
Channels
plain: general, dot: general, line: general, pipe: general, bracket: general, arrow: general, star: general, emoji: general
Roles
plain: Admin, UPPER: ADMIN, dot: Admin, bracket: Admin, emoji: Admin, star: Admin
Per-channel emoji is not global. Each channel gets its own emoji: welcome, rules, announcements, general, lfg, tournaments, etc. Custom separator lets you type any separator and optionally toggle Add per-channel emoji with a custom emoji input. Same for roles.
Aesthetic only renames. Permissions and audit-locks stay intact. You can still edit everything after.
Template builder
Template = { roles, categories: [{ name, channels: [{ name, type, permissions? }] }] }. Stored in Supabase templates with user_id ownership.
Roles
Name + color + permissions + hoist (Separate/Group). Drag to reorder. @everyone is implicit, not stored.
Categories & channels
Text / voice / announcement. Drag grip to reorder across categories. Type is a subtle pill (icon-only) separate from the permissions key. Channel overwrites edited via modal: allow/deny per role, with presets.
Drafts
Autosaved to localStorage alteros:draft:guild:template every 800ms. Restore banner on reload, discard restores server version.
Import
discord.new
Paste discord.new/XYZ or discord.com/template/XYZ or raw code. Calls GET /guilds/templates/{code} (public, no bot auth), maps serialized_source_guild to categories/channels + roles (skips @everyone id 0). Base64url codes handled.
Store
Browse, Import copies store template into your templates. Audited before publish.
JSON
Export any template as JSON and re-import via file picker or paste modal. Validates roles/categories.
Blocks
Admin, Blocks curates reusable fragments. getPublicBlocks is public, mergeStructures(a,b) unions roles/categories and deny-wins overwrites. Future editor left rail will let you stack blocks.
Table blocks (RLS) with grade/featured/visible toggles, live audit preview, duplicate, tags. Migration 20260812000000_blocks.sql.
Deploy & Manage
Apply changes
Create missing + update matching (by name). Never deletes. Safe to run repeatedly.
Replace server
Exact sync. Matching items keep Snowflake IDs (webhooks/integrations intact), removed items deleted. Bot hierarchy matters.
Manage (live)
Direct live editor at /manage with same StructureEditor but Apply morphs roles/categories/channels in place.
Sync
Snapshot live server into a new template (roles except @everyone/managed, all channels, overwrites). Sync, edit, deploy elsewhere.
Team
Add members by Discord ID, assign roles (admin/editor), submit push requests for owner approval before deploy.
Members
Owner can add/remove members. Each member has a role (admin or editor) that controls what they can do.
Push requests
Members submit changes for review. Owner approves or rejects. Resubmit on reject. Owner badge displayed on the team member list.
Audit
Read-only scan. Live via auditServer (bot reads roles/channels) or offline via auditTemplateStructure(structure). Deterministic, not LLM.
Checks (14 groups)
- @everyone admin / 13 base dangers (manage_guild etc.)
- Admin roles + too-many-admins 4+
- Per-role dangerous base (manage_roles critical, etc.) + excessive 3+
- @everyone overwrites + per-role overwrites
- Announcements open, staff channels/categories leaks
- Broken inheritance, ghost webhooks, unauthorized invites
- Hygiene: loose channels, bloat (roles 25+, channels 45+), empty categories, announcement sprawl, @everyone create_invite
Scoring math
Weights critical 35, high 14, medium 6, low 2, info 0. Dampening: 4th+ finding of same severity x0.55, 6th+ x0.4. Exposure: @everyone x1.35, staff x1.15. Score = 100 - penalty (soft knee under 25). Grades: 95 A+, 90 A, 80 B, 65 C, 50 D, else F.
Checks tagged for UI: permission-creep, broken-inheritance, ghost-webhooks, unauthorized-invites, hygiene, invite-hygiene to 6 cards in audit UI.
Auto-fix
Fix buttons flip only the offending bits (role deny, overwrite deny, channel_lock, webhook_delete). Hold-to-confirm sheet, live log, then rescan.
Architecture
TanStack Start on Vercel. Nitro auto-generates .vercel/output/config.json (no vercel.json needed). Server functions in template.functions.ts call Discord REST directly with DISCORD_BOT_TOKEN (no worker). Supabase for auth + templates/blocks/store. Env loaded only via vite.config.ts.
FAQ
Is AlterOS free?
Yes. Templates, onboarding, import, blocks, sync, audit, store, team. All free.
Does Replace delete?
Only items the template no longer has. Matching items keep IDs, so webhooks and MEE6/Carl stay linked.
What does the audit change?
Nothing until you click Fix. Flips only the bits flagged. Reversible in Server Settings.
Why is my new template empty?
You chose Start empty. Re-open guided setup via the button above the editor.
Still need help? Email us