Self-host on Discord
Everything needed to run your own instance: install, configuration, a reverse proxy, upgrades and rollback, and a troubleshooting table. For what each feature does, see Modules.
Sylo is a single Node 22 process — the Discord bot and the web dashboard in one. No build step. All state is one SQLite file under a mounted data directory by default — that’s the right choice for nearly everyone; see Postgres (optional) if you’re running at hosted scale and want the optional Postgres backend instead.
Quick start
Section titled “Quick start”git clone https://github.com/Ferdinand99/Sylo.gitcd Sylonpm installcp .env.example .env # fill in DISCORD_TOKEN and DISCORD_CLIENT_IDnpm startOr with Docker:
cp .env.example .envdocker compose up -d --builddocker compose logs -f syloThe dashboard is then on http://<host>:${WEB_PORT:-3000} and the database
persists in ./data.
For fast iteration set DISCORD_DEV_GUILD_IDS to a test server’s id — commands
register to it instantly instead of taking up to ~1 hour globally. npm run register re-syncs commands without a restart.
Environment variables
Section titled “Environment variables”Only DISCORD_TOKEN and DISCORD_CLIENT_ID are required, unless you run on
Fluxer only: then FLUXER_TOKEN and FLUXER_CLIENT_ID replace them.
At least one platform must be configured.
| Variable | Default | Description |
|---|---|---|
DISCORD_TOKEN |
— | Bot token (required) |
DISCORD_CLIENT_ID |
— | Application (client) id (required) |
DISCORD_DEV_GUILD_IDS |
— | Register commands instantly to one or more servers (comma/space-separated) instead of globally. Old name DISCORD_GUILD_ID still works (warns). |
DISCORD_SHARD_COUNT |
auto |
Internal gateway shards for this one process. auto follows Discord’s recommendation and stays at 1 below ~2,500 servers; pin an integer to override. Multi-process sharding is not supported. |
FLUXER_TOKEN |
— | Optional: bot token for Fluxer. Setting it runs Sylo on Fluxer too (experimental) |
FLUXER_CLIENT_ID |
— | Fluxer application id (required with FLUXER_TOKEN) |
FLUXER_WEB_URL |
hosted Fluxer | Web app origin of a self-hosted Fluxer instance, e.g. https://chat.example.com |
COMMAND_PREFIX |
! |
Default chat prefix for commands on Fluxer, which has no slash commands (1–5 characters); each server can set its own in Settings |
APPLE_KEY_ID |
— | Optional: App Store Connect API key id for the owner-only App Store Connect module |
APPLE_ISSUER_ID |
— | Issuer id of a team API key (leave unset for an individual key) |
APPLE_PRIVATE_KEY |
— | The key’s .p8 file: PEM text, PEM on one line with literal \n, or base64 |
APPLE_VENDOR_NUMBER |
— | Optional vendor number for a planned daily downloads digest |
TRUST_PROXY |
one private hop with DASHBOARD_URL |
Which proxies may set X-Forwarded-For: false, a hop count, or addresses/subnets. See Behind a reverse proxy |
ALLOW_PRIVATE_URLS |
false |
Let server admins use feed and image URLs on private, loopback or link-local addresses (your own network). Off by default: those URLs are fetched by the server |
PUSH_RELAY_URL |
https://app.sylobot.com |
Where this instance sends Sylo app notifications; empty turns them off |
PIGEON_URL |
— | Set to https://pigeon.hedgerow.tools to send Sylo app notifications through Postal Pigeon, the Hedgerow push relay, for apps that support it. Unset or empty: off |
APNS_KEY_ID |
— | Only for the instance that talks to Apple itself (the hosted Sylo): APNs auth key id |
APNS_TEAM_ID |
— | The Apple developer team id that owns the key |
APNS_PRIVATE_KEY |
— | The APNs key’s .p8 file: PEM text, PEM on one line with literal \n, or base64 |
APNS_TOPIC |
net.opland.sylo |
The app’s bundle id |
FLUXER_CLIENT_SECRET |
— | Adds “Log in with Fluxer” to the dashboard |
FLUXER_OWNER_IDS |
— | Your Fluxer user id(s); the Fluxer counterpart of OWNER_IDS |
WEB_PORT |
3000 |
Dashboard HTTP port |
DISCORD_CLIENT_SECRET |
— | Set to require “Log in with Discord” on the dashboard |
SESSION_SECRET |
generated, kept in <data>/session-secret |
Signs the session cookie and the verify/appeal links. Optional: Sylo makes one and keeps it next to the database, so logins survive restarts. Set it only to use your own value; when set, it wins over the file |
CSP_REPORT_ONLY |
0 |
1 reports the dashboard’s Content-Security-Policy instead of enforcing it. A way back if a custom setup trips the policy; see Upgrading to 5.0 |
OWNER_IDS |
— | Your Discord user id(s), comma/space-separated. Gates /health to just these accounts when DISCORD_CLIENT_SECRET is set — everyone else is blocked, not just non-admins |
DEV_LOG_CHANNEL_ID |
— | A channel id Sylo posts its own errors to — a “dev-log”, separate from any per-guild logging/modlog channel. Optional: errors and warnings are stored either way, and the Sylo app shows them and can notify operators |
DASHBOARD_URL |
derived | Public dashboard URL; needed behind a reverse proxy and for verification-captcha / ban-appeal links |
TURNSTILE_SITE_KEY |
— | Cloudflare Turnstile site key — enables the Verification captcha mode |
TURNSTILE_SECRET_KEY |
— | Cloudflare Turnstile secret key (pair with the site key) |
DASHBOARD_ERROR_DSN |
— | Optional: send the dashboard’s browser errors to your own Sentry or Keen Kestrel, with this DSN. Unset (default): nothing is sent anywhere. If you set it, your privacy policy should say so |
DASHBOARD_VISIT_STATS |
false |
With a Keen Kestrel DASHBOARD_ERROR_DSN: also count dashboard page views with its k.js (no cookies, no stored IP addresses) |
BOT_ERROR_DSN |
— | Optional: send the bot’s errors (everything it logs as an error) to your own Sentry or Keen Kestrel. Unset (default): nothing is sent |
ERROR_ENVIRONMENT |
production |
The environment name on the bot’s and the dashboard’s error reports |
ITAD_API_KEY |
— | IsThereAnyDeal key — adds non-Epic stores to the Free games module |
INTENT_GUILD_MEMBERS |
true |
Request the Server Members privileged intent |
INTENT_MESSAGE_CONTENT |
true |
Request the Message Content privileged intent |
GAMETOOLS_API_BASE |
https://api.gametools.network |
Stats API base URL |
STATS_CACHE_TTL_MINUTES |
5 |
How long stats lookups are cached |
DATABASE_PATH |
./data/sylo.db |
SQLite file path |
DATABASE_URL |
— | Optional: a postgres:// URL to use Postgres instead of SQLite. Hosted-scale deployments only — see Postgres (optional), and use a role with few rights (from Sylo 5.3, Sylo warns when it has more), not a superuser. Unset (default) means nothing about the setup below changes. |
BACKUP_INTERVAL_HOURS |
24 |
Scheduled DB snapshot interval; 0 disables it (pre-migration + manual still run) |
BACKUP_RETENTION |
14 |
How many DB snapshots to keep in <data>/backups |
BACKUP_DIR |
<db dir>/backups |
Where DB snapshots are written |
UPDATE_CHECK |
on |
Sylo 5.3. The update notice for operators: Sylo looks up its newest GitHub release (at most every 6 hours). off turns it off and nothing is requested |
WISE_WREN_URL |
— | Sylo 5.3. Optional: address of your Wise Wren, to update Sylo from the dashboard. Needs the next two as well. https, or http on your own network |
WISE_WREN_TOKEN |
— | Sylo 5.3, and Wise Wren 0.4 (not released yet). A Wise Wren target token for Sylo’s target (Wise Wren: Settings → Target tokens): it can read and approve only that target. A secret: never shown in the dashboard, never logged |
WISE_WREN_TARGET_ID |
— | Sylo 5.3. The id of Sylo’s target in Wise Wren (the number in the target page’s address) |
WISE_WREN_ALLOW_OPEN_MODE |
false |
Sylo 5.3. Only matters when the dashboard has no login (open mode): then Update now is refused, because anyone who can reach the dashboard could use it. true allows it anyway |
LOG_LEVEL |
info |
debug / info / warn / error |
LOG_FORMAT |
text |
text or json (LOG_JSON=1 = json) |
NODE_ENV |
development |
Set to production in deployment |
Privileged intents
Section titled “Privileged intents”Both privileged intents default on. Several modules need them:
| Intent | Env var | Modules that need it |
|---|---|---|
| Server Members | INTENT_GUILD_MEMBERS |
logging, roles, verification, welcome, leveling, server-stats, invite-tracker |
| Message Content | INTENT_MESSAGE_CONTENT |
logging, autoresponder, counting, automod, starboard; the Quote board’s /quote save <message link> (its “Save quote” menu works without) |
Enable them on the Discord Developer Portal (Bot → Privileged Gateway
Intents). If you don’t want those modules, set the env var to false and Sylo
starts without requesting that intent. A verified bot (100+ servers) needs
Discord’s approval for Message Content.
Discord application setup
Section titled “Discord application setup”-
https://discord.com/developers/applications → New Application.
-
Bot tab → Reset Token → copy into
DISCORD_TOKEN. Enable the privileged intents you need (see above). -
General Information → copy Application ID into
DISCORD_CLIENT_ID. -
OAuth2 → URL Generator → scopes
bot+applications.commands. Bot permissions:- Send Messages, Embed Links — always
- Attach Files — welcome images, rank cards, leaderboard cards
- Kick Members, Ban Members, Moderate Members, Manage Messages — moderation
- Manage Channels —
/lock,/lockdown,/slowmode, temporary voice - Manage Roles — reaction roles, autoroles, verification, leveling rewards, birthday role
- Move Members — temporary voice channels
- Manage Server — invite tracker (reads the invite list) and the automod
push to native Discord AutoMod (creates/edits
Sylo:-named rules)
Open the generated URL to invite the bot. Tickets need no extra permission — just leave the bot able to receive DMs.
-
Drag Sylo’s role above the roles it should manage in Server Settings → Roles. The bot can never kick/ban/timeout someone whose highest role sits above its own, or edit a role above its own.
Dashboard authentication
Section titled “Dashboard authentication”Running on Fluxer too? The login steps for it (client secret, redirect URL,
FLUXER_OWNER_IDS, linking both accounts) are in Sylo on Fluxer.
By default the dashboard runs open (no login) — only safe on localhost or a
trusted LAN. Even in open mode a same-origin check blocks cross-site form posts.
To require a login:
- Developer Portal → your app → OAuth2 → copy the Client Secret into
DISCORD_CLIENT_SECRET. - Same page → Redirects → add
<DASHBOARD_URL>/auth/discord/callback(e.g.http://192.168.1.10:3000/auth/discord/callback, or the public HTTPS URL behind a proxy). - Nothing to do for
SESSION_SECRET: Sylo generates one and keeps it in<data>/session-secret(back it up with the data folder). SetSESSION_SECRETyourself only if you want to choose the value. - Set
OWNER_IDSto your own Discord user id — without it,/health(status, error log, database backup/restore) is reachable by no one, not even you.
With DISCORD_CLIENT_SECRET set, every page except the /health JSON and the
/metrics scrape endpoint requires “Log in with Discord”. Per-server pages
require Manage Server (or Administrator / owner) in that server, or one of the
roles set under Dashboard access on that server’s Settings page: Edit
(the bot-master roles: everything), Inbox (tickets, ban appeals, applications
and suggestions, and reading the rest) or View (the pages and settings, read
only, without what the inboxes contain). Only the owner or someone with Manage
Server can change the Edit roles; anyone with Edit can change the Inbox and View
roles and save the rest of that page. With INTENT_GUILD_MEMBERS=false Sylo
fetches a member from Discord before their role decides access (on every change,
and at most once a minute for reading), because the bot is not told when roles
change.
/health (JSON) and /metrics stay unauthenticated so a monitor or Prometheus
can reach them — keep them on your LAN, or restrict them at the reverse proxy if
the dashboard is public.
For an uptime monitor, check $.status is ok and $.errorsLastHour is 0 in the
/health JSON. errorCount counts every error since the last restart, so one old
error would keep such a monitor down. App Store Connect server errors on Apple’s side
are retried once and logged as warnings, not errors.
Point Prometheus at <host>:<WEB_PORT>/metrics and import
docs/grafana-dashboard.json for a ready-made overview (gateway health, guild
count, HTTP and command rates, DB size, module adoption).
Off-site backups
Section titled “Off-site backups”Every local snapshot can also be shipped, gzipped, to a remote target — set any
of BACKUP_WEBDAV_URL (+ BACKUP_WEBDAV_USER / BACKUP_WEBDAV_PASS, e.g. a
Nextcloud folder) or BACKUP_WEBHOOK_URL (a Discord webhook; attachments over
~8 MiB are skipped). Uploads are best-effort and logged; they never hold up the
local backup. The Health page shows which targets are active.
An off-site copy is the whole database (webhook secrets, ticket text, push
tokens). Set BACKUP_ENCRYPTION_KEY to a long passphrase and each copy leaves
encrypted (AES-256-GCM, <name>.db.gz.enc). Keep the passphrase somewhere other
than the server: without it the copies cannot be read. To restore one, decrypt it
first, then restore the .db file as usual:
BACKUP_ENCRYPTION_KEY='your passphrase' node scripts/decrypt-backup.js sylo-2026-10-17.db.gz.encWith BACKUP_WEBDAV_USER set, BACKUP_WEBDAV_URL must be https:// (or an
address on your own network, such as a container name or a 192.168.x.x
address): Basic auth over plain http sends the password in clear text.
Behind a reverse proxy
Section titled “Behind a reverse proxy”Set DASHBOARD_URL to the public URL and proxy to 127.0.0.1:${WEB_PORT}. Sylo
then trusts one proxy hop (X-Forwarded-*), which it needs for correct client
IPs (rate limiting) and OAuth redirects. Make sure the OAuth redirect in the
Developer Portal matches <DASHBOARD_URL>/auth/discord/callback.
Exactly one hop: with two proxies in a row (for example Cloudflare in front of nginx), every request looks like it comes from the inner proxy, so all clients share one rate-limit bucket. Put only one HTTP proxy in front of Sylo.
The proxy must connect from this machine or the local network (a loopback or
private address, such as another container). X-Forwarded-For from any other
address is ignored, so a client that reaches Sylo’s port directly cannot choose
its own IP. For another setup, set TRUST_PROXY: false, a hop count, or the
proxy’s addresses or subnets (comma-separated, as Express takes them).
Set TRUST_PROXY explicitly
Section titled “Set TRUST_PROXY explicitly”The default (one hop, from a private or loopback peer) is a convenience, and it
has a limit you should know about. A “private peer” includes the Docker bridge.
If you publish Sylo’s port straight from Docker (-p 3000:3000) with no reverse
proxy in front, every outside client reaches Sylo from the bridge gateway (an
172.x address), which counts as a trusted proxy. Any client can then send its
own X-Forwarded-For header and pick the address Sylo rate limits it under, so
the per-client limits on sign-in, OAuth, the mobile app token exchange and the
push relay can be walked around. Nothing else about authentication changes: a
session or app token is still needed for the dashboard.
Sylo logs a warning at startup when it runs with this default and a public
https DASHBOARD_URL. To close the gap, do one of these:
- Set
TRUST_PROXYto your proxy’s address or subnet, for exampleTRUST_PROXY=172.18.0.5orTRUST_PROXY=loopback, so only that peer is believed. A hop count (TRUST_PROXY=1) is also explicit, but it trusts whatever connects, so it only fits when Sylo is reachable through the proxy alone. - Publish the port on the loopback address only when the proxy runs on the same
host:
ports: ["127.0.0.1:3000:3000"]indocker-compose.yml. - With no proxy at all, set
TRUST_PROXY=false. Sylo then uses the connection’s own address and ignoresX-Forwarded-For.
The shipped default is not changed, because installs with a reverse proxy in a neighbouring container rely on it.
Without a login (open mode), the dashboard only answers on local names and
addresses (localhost, an IP address, a name without dots, .local, .lan,
.home.arpa, .internal) and on the host in DASHBOARD_URL. That blocks other
websites from reaching it through DNS rebinding.
Caddy
sylo.example.com { reverse_proxy 127.0.0.1:3000}nginx
server { listen 443 ssl; server_name sylo.example.com; # ssl_certificate ... ;
location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }}DASHBOARD_URL=https://sylo.example.comDocker
Section titled “Docker”The bundled docker-compose.yml builds from source, mounts ./data, and sets a
restart policy (needed so a dashboard Restore can restart the container).
cp .env.example .envdocker compose up -d --buildPrebuilt images
Section titled “Prebuilt images”CI publishes multi-arch (linux/amd64 + linux/arm64) images to two registries:
| Tag | Registry | What it is |
|---|---|---|
iwgamin/sylo:latest, :X.Y.Z, :X.Y |
Docker Hub · GHCR | Stable releases. What the Unraid template pulls. |
ghcr.io/ferdinand99/sylo:main, :sha-<short> |
GHCR only | Rolling build of main — every push. |
docker run -d --name sylo -p 3000:3000 --env-file .env \ -v "$PWD/data:/app/data" --restart unless-stopped iwgamin/sylo:latestIf better-sqlite3 ever fails to build on Alpine for your platform, change the
two FROM node:22-alpine lines in the Dockerfile to node:22-slim.
Unraid
Section titled “Unraid”Sylo is in the Unraid Community Applications store — search “Sylo”. The
template’s source of truth is
Ferdinand99/unraid-templates
(templates/sylo.xml) — edits there propagate to existing installs
automatically via <TemplateURL>, so no re-submission is needed for config
changes. If Community Applications hasn’t picked up that repository yet, add
https://github.com/Ferdinand99/unraid-templates under Docker → Template
repositories to install the current template directly.
Manual container setup (Docker tab → Add Container):
| Field | Value |
|---|---|
| Repository | docker.io/iwgamin/sylo:latest |
| Network | bridge |
| Port | Container 3000 → Host 3000 |
| Path | Container /app/data → a real local path (see the caveat below) |
| Variable | DISCORD_TOKEN, DISCORD_CLIENT_ID, NODE_ENV=production |
The image starts as root only long enough to fix ownership of the data
directory, then runs as an unprivileged user (sylo, uid 100). A fresh
root-owned folder works out of the box. If you still see SQLITE_CANTOPEN, run
once: chown -R 100:101 <data path>.
SQLite on a network mount
Section titled “SQLite on a network mount”Put the data directory on a real local disk, not a network share.
better-sqlite3 uses WAL mode, which needs working file locks and mmap. SMB,
NFS, Unraid’s /mnt/user (shfs / FUSE) and some Docker-Desktop bind mounts don’t
provide them reliably, and you get SQLITE_IOERR, database is locked, or
silent corruption.
- Unraid: use a cache-pool path such as
/mnt/cache/appdata/sylo, or a disk-share path like/mnt/disk1/appdata/sylo— not/mnt/user/.... - NAS / remote: run Sylo on the box that owns the disk, or use a local volume.
Backups
Section titled “Backups”All state is one SQLite file (data/sylo.db + -wal / -shm sidecars) —
this section assumes that default setup. Running with DATABASE_URL set
instead? See Postgres (optional)
— the same buttons and flow, pg_dump/pg_restore under the hood.
Automatic snapshots are written to data/backups/: one before any schema
migration, one shortly after start, and one every BACKUP_INTERVAL_HOURS
(default 24), keeping the newest BACKUP_RETENTION (default 14). Set
BACKUP_INTERVAL_HOURS=0 to keep only the pre-migration and manual ones.
From the dashboard Health page you can create a snapshot now, import a .db
from another machine (validated: SQLite header, integrity_check, schema no
newer than this build), download any snapshot, and Restore — which takes a
prerestore snapshot, swaps the file, and exits so the container restarts on the
restored data (needs a restart policy).
Manual restore: stop the container, copy a snapshot over data/sylo.db
(delete the -wal / -shm sidecars first), start again. Migrations only ever
move the schema forward; Sylo runs a quick_check on boot and logs corruption.
Per-server module config can also be exported as JSON from General → Backup.
Upgrades and rollback
Section titled “Upgrades and rollback”Upgrade (prebuilt image):
docker compose pull # or: docker pull iwgamin/sylo:latestdocker compose up -dUpgrade (from source):
git pullnpm installnpm run build:v2 # the dashboard (web-v2/dist); without it /v2 shows only a short note# restart the process / containerOn start, Sylo applies any new schema migrations inside a transaction, taking a
sylo-premigrate-vN-*.db snapshot first.
Rollback: pull the previous image tag (iwgamin/sylo:3.4.1), or git checkout the previous tag, then restore the matching sylo-premigrate-* (or a
dated) snapshot from data/backups/ over data/sylo.db. A newer database can’t
be opened by an older build — the schema check refuses it — so always roll the
database back together with the code.
Update notice and “Update now”
Section titled “Update notice and “Update now””The people who run the instance (the operators, OWNER_IDS / FLUXER_OWNER_IDS) see a small
Update available note in the dashboard’s top bar when a newer Sylo release is out. It opens the
Updates section of the Health page: the new version, its release notes, and the command to copy,
docker compose pull && docker compose up -d. Server admins who are not operators see none of this,
and the Sylo app shows the same to operators (see The Sylo app).
-
How it checks. Sylo asks
api.github.comfor its latest release, anonymously, when an operator opens the dashboard, and keeps the answer for 6 hours. Nothing about your instance is sent (GitHub sees your server’s address, as for any request). A failed check is quiet (one log line) and never delays startup. To turn it off completely, setUPDATE_CHECK=off; Sylo then makes no request, and the Health page says the check is off. -
Without any setup, the notice and the command are all you get: you run the command yourself. Sylo itself never gets access to the Docker socket (that would be root on the host).
-
Updating without the command line (optional). If you run Wise Wren, it can do the update, and the dashboard gets an Update now button. This needs a Wise Wren version with target tokens, Wise Wren 0.4, which is not released yet:
- In Wise Wren, make sure Sylo shows up as a target and that the agent’s
[updates]allow list includes it. - In Wise Wren, make a target token (Settings → Target tokens) for that target. It can read and
approve that one target and nothing else, so a leaked token cannot update anything else. Use the
token’s
ww_…value below. - Set
WISE_WREN_URL,WISE_WREN_TOKENandWISE_WREN_TARGET_ID(all three) and restart Sylo.
Sylo then shows what Wise Wren sees for the target. Update now (operators only, after a confirmation) approves that exact version in Wise Wren, which stops Sylo, takes a snapshot, starts the new version and rolls back if it does not come up healthy. The Health page follows the run and reconnects by itself when Sylo restarts. Sylo remembers the run it approved (in its database), so Update now stays off while that run is going, also after the restart. If Wise Wren refuses (the version changed, a run is already going, the target only notifies), you see Wise Wren’s own words. The token stays on the server: it is never sent to the browser or the app, and never logged. Sylo only calls three Wise Wren routes, all for the one target:
GET /api/v1/targets/<id>,POST /api/v1/targets/<id>/approveandGET /api/v1/runs/<id>. Without these settings only the notice and the command are shown. - In Wise Wren, make sure Sylo shows up as a target and that the agent’s
-
Open mode. When the dashboard has no login (no
DISCORD_CLIENT_SECRETorFLUXER_CLIENT_SECRET), everyone who can reach it counts as an operator. Update now is refused there (the notice, the command and what Wise Wren sees are still shown, and Sylo logs a warning at start), because it spends Sylo’s Wise Wren token on behalf of whoever sent the request. Set up a login, or setWISE_WREN_ALLOW_OPEN_MODE=trueif you accept that on a network you trust.
Upgrading to 5.2
Section titled “Upgrading to 5.2”Sylo 5.2 needs no manual steps beyond the usual upgrade described above, unless you
run Sylo behind a reverse proxy (see DASHBOARD_URL below).
- Database migrations 73 to 80 run on start (from 5.1). On SQLite Sylo writes
the usual
sylo-premigrate-vN-*.dbbackup first. As always, roll the database back together with the code if you go back to an older version. - Behind a reverse proxy, set
DASHBOARD_URLto your public address. The Sylo app now checks that a sign-in or connect callback came from the server it signed in to, and Sylo names its own address in that callback. - New dashboard access levels. Roles can now get View, Inbox or Edit access to a server’s dashboard. Nothing changes for existing bot-master roles: they keep full access (the Edit level). See Dashboard access levels.
Upgrading to 5.0
Section titled “Upgrading to 5.0”Sylo 5.0 removes the classic dashboard. There are no database steps: just upgrade as described above.
- The classic dashboard is gone. The React dashboard (V2) is the only one. The
/?classic=1switch, the “Back to classic dashboard” link and the old server-rendered pages no longer exist. The public pages (login, verify, appeal, leaderboard, quotes) look like the dashboard now. - Reminders keep their pings. A server that already has reminders keeps pinging
@everyone,@hereand roles as before; new servers start with pings off and the owner or Manage Server can change it on the Reminders page. - Old bookmarks and Discord links still work. Old addresses such as
/guilds/<id>/…,/account,/settings,/statsand/commandsredirect to the matching page in the dashboard. - From source, run
npm run build:v2afternpm install. The Docker image already contains the build. Without it/v2shows only a short plain-text note. - The session secret now lives in a file. If
SESSION_SECRETis not set, Sylo creates<data>/session-secreton first start (next to the database, for exampledata/session-secret) and keeps using it, so logins survive restarts. Back it up with the data folder; if it is lost, everyone just has to log in again. ASESSION_SECRETin the environment still wins over the file. Thedata/folder must be a volume (a Docker volume or bind mount, for example./data:/app/data), also when you use Postgres: if it lives only inside the container, the secret is lost whenever the container is replaced and everyone is logged out. On Linux, Sylo logs a warning at start-up when it can see that a Postgres install keeps the secret in a folder that is not a mounted volume; settingSESSION_SECRETis the other way out. - A strict Content-Security-Policy and HSTS are on. The dashboard now sends an enforcing
Content-Security-Policy(scripts, styles and connections from Sylo itself, plus the error-reporting host and Cloudflare Turnstile where you configured them), andStrict-Transport-SecuritywhenDASHBOARD_URLis https. Normally you notice nothing. If a custom setup breaks (for example a proxy that injects its own scripts into the page), setCSP_REPORT_ONLY=1and restart: the browser then only logs violations to its console instead of blocking them. Use it to find what is being blocked, not as a permanent setting; the policy is there to protect the logged-in admin session. - YouTube alerts use push when Sylo has a public address. With
DASHBOARD_URLset to a publichttpsaddress (not an IP address,localhostor a LAN name), Sylo subscribes to YouTube’s WebSub hub and announces new videos within seconds. YouTube must be able to reach<DASHBOARD_URL>/webhooks/youtube/<channel id>, so the reverse proxy has to forward it and keep theHostheader. Otherwise Sylo polls every few minutes, as before. Nothing to configure either way. Sylo only accepts the hub’s verification request for a subscription it asked for itself in the last 10 minutes, and never keeps a lease longer than the 5 days it asked for. - Five command names are now built in:
suggest,suggestion,quote,eventandtemprole. A built-in command always wins over a custom command of the same name. If a server made a custom command with one of these names in 4.10, Sylo no longer registers it after the upgrade, logs a warning (one per server and command), and the Custom commands page marks it “Rename needed”. Rename the command there and it works again. This is checked against the commands Sylo actually has, so it also covers any built-in added later. - No database steps. Migrations run on start as always, with the usual pre-migration snapshot.
Upgrading to 4.10
Section titled “Upgrading to 4.10”- The new dashboard is the default for everyone, open mode included.
/opens/v2, and old dashboard addresses (/guilds/<id>/…,/account,/settings,/healthin a browser,/stats,/commands) open the matching page there. Bookmarks and links Sylo posted in Discord keep working. - The classic dashboard is retiring. Opening
/?classic=1(the home page, not another address) keeps a browser on it until/v2is opened again; with a login the choice is kept in the session cookie, without one in a small cookie of its own. It is removed in Sylo 5.0. - The command list and the roadmap are public at
/v2/commandsand/v2/roadmap; voting and suggesting still need a login. - Monitoring is unchanged:
GET /healthstill answers JSON to monitors and the container health check. - From source: run
npm run build:v2afternpm install; the Docker image already contains the build.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause / fix |
|---|---|
Used disallowed intents on start |
A privileged intent is requested but not enabled in the Developer Portal. Enable it, or set INTENT_GUILD_MEMBERS=false / INTENT_MESSAGE_CONTENT=false. |
| Slash commands don’t appear | Global registration takes up to ~1 hour. Set DISCORD_DEV_GUILD_IDS for instant per-server registration, or wait. npm run register re-syncs. |
“Log in with Discord” loops / redirect_uri mismatch |
The Developer Portal Redirect must exactly equal <DASHBOARD_URL>/auth/discord/callback, scheme and port included. |
SQLITE_CANTOPEN |
The data directory isn’t writable by uid 100. chown -R 100:101 <data path>. |
SQLITE_IOERR, database is locked, corruption |
The database is on a network share. Move it to a local disk — see SQLite on a network mount. |
better-sqlite3 fails to build |
Switch the Dockerfile base images to node:22-slim, or install python3 make g++ for a from-source build. |
| Moderation says it can’t act on a member | Sylo’s highest role must sit above the target’s, and it needs the relevant permission (Ban/Kick/Moderate Members). |
| Welcome image / rank card missing | The bot lacks Attach Files in that channel, or @napi-rs/canvas didn’t load on this platform (a warning is logged; the text message still sends). |
| Dashboard shows “open mode — no auth” | DISCORD_CLIENT_SECRET isn’t set. That’s expected for LAN use; set it to require a login. |