- Text channels — Markdown, replies, reactions, and live typing indicators.
+ Text channels. Markdown, replies, reactions, and live typing indicators.
|
- Screen-share controls — resolution, frame rate, codec, and bitrate, within admin-set bounds.
+ Screen-share controls. Resolution, frame rate, codec, and bitrate, within admin-set bounds.
|
- Spaces & discovery — browse public, request-to-join, and joined spaces.
+ Spaces and discovery. Browse public, request-to-join, and joined spaces.
|
- Direct messages — 1-on-1 and group DMs, including members on peer instances.
+ Direct messages. 1-on-1 and group DMs, including members on peer instances.
|
- Friends & social — find people across instances with mutual friends and spaces.
+ Friends and social. Find people across instances with mutual friends and spaces.
|
- Federation admin — manage peered instances, relay, and secret rotation.
+ Federation admin. Manage peered instances, relay, and secret rotation.
|
@@ -106,22 +106,22 @@ You own the server, the data, and the network it federates into.
- Message reactions, replies, editing, deletion, and per-message mark-as-unread
- Rich link embeds (YouTube, Vimeo, Spotify, and generic OpenGraph) with SSRF-protected scraping, plus GIF search (Klipy)
- Typing indicators, unread badges, and presence
-- Direct messages — 1-on-1 and group DMs (up to 10 people), with voice/video calls (ring / accept / reject)
+- Direct messages: 1-on-1 and group DMs (up to 10 people), with voice/video calls (ring, accept, reject)
-**Voice, video & screen sharing** (via [LiveKit](https://livekit.io/)):
-- Screen sharing up to 4K / 120fps — VP9 by default, an optional hardware-accelerated H.264 mode, and a VP8 simulcast fallback
-- Per-stream quality controls — resolution, frame rate, codec, and bitrate, within admin-set bounds
-- Independent 0–200% volume for every participant *and* every screen-share
+**Voice, video, and screen sharing** (via [LiveKit](https://livekit.io/)):
+- Screen sharing up to 4K/120fps: VP9 by default, an optional hardware-accelerated H.264 mode, and a VP8 simulcast fallback
+- Per-stream quality controls: resolution, frame rate, codec, and bitrate, within admin-set bounds
+- Independent 0-200% volume for every participant and every screen-share
- RNNoise noise suppression (on by default), plus echo-cancellation and auto-gain toggles and mic/speaker device selection
-- Live connection inspector — per-participant bitrate, codec, ping, packet loss, and jitter — plus a per-tile badge showing each stream's measured resolution/frame-rate
+- Live connection inspector for per-participant bitrate, codec, ping, packet loss, and jitter, plus a per-tile badge showing each stream's measured resolution and frame-rate
- Screen-share viewer detection ("who's watching") and auto-ducking that lowers stream audio when someone speaks
-- Selective subscription — mute or stop watching any camera/stream to save bandwidth
+- Selective subscription: mute or stop watching any camera or stream to save bandwidth
- Push-to-talk and fully customizable keybinds (including mouse buttons), in the browser and the desktop app
- Picture-in-Picture for voice and video
### Organization
- Spaces with channel categories
-- Role-based permissions — bitwise RBAC with category- and channel-level overrides
+- Role-based permissions: bitwise RBAC with category- and channel-level overrides
- Customizable user sidebar layout, with personal color-coded folders that group whole spaces
- Space discovery (public, request-to-join, and private)
- Shareable invite codes
@@ -132,8 +132,8 @@ You own the server, the data, and the network it federates into.
- Mutual friends and mutual spaces
- User profiles with banner, bio, and accent color
- Presence and rich activities (playing, listening, watching, streaming, custom)
-- Manual status — Online, Idle, or Do Not Disturb — with a custom status message
-- Privacy controls — toggle discoverability and activity-status sharing
+- Manual status (Online, Idle, or Do Not Disturb) with a custom status message
+- Privacy controls: toggle discoverability and activity-status sharing
### Moderation
- Bans with reason and moderator attribution (who, why, and when)
@@ -144,7 +144,7 @@ You own the server, the data, and the network it federates into.
### Federation
- Multi-instance peering with HMAC-signed server-to-server requests
- Federated identity resolution (`username@instance`)
-- Cross-instance DMs — messages, reactions, and membership relay
+- Cross-instance DMs: messages, reactions, and membership relay
- Cross-instance friends and presence
- File replication with size validation
- Background workers for outbox delivery, file download, peer health, and cleanup
@@ -152,27 +152,27 @@ You own the server, the data, and the network it federates into.
### Platform
- File uploads with image thumbnails (via `sharp`), drag-and-drop and paste-to-upload, and in-app avatar/banner cropping
- Message search with `from:`, `has:`, `before:`, and `after:` filters, plus jump-to-message
-- Admin panel — instance settings, user management, registration controls, storage management, and federation/peering, plus granular streaming controls (a per-resolution × per-frame-rate bitrate matrix, min/max caps, quality-slider step, and an optional user-set-bitrate mode)
+- Admin panel: instance settings, user management, registration controls, storage management, and federation/peering, plus granular streaming controls (a per-resolution by per-frame-rate bitrate matrix, min/max caps, quality-slider step, and an optional user-set-bitrate mode)
- Automatic SQLite backups (pre-migration, scheduled, and manual) with restore tooling
- Electron desktop app (Windows, macOS, Linux) with global keybinds (push-to-talk, mute, deafen) and activity detection
- Native desktop notifications and unread badge counts
- Mobile-responsive web UI with a dedicated touch layout (bottom navigation, swipe gestures, full-screen views)
-- Installable PWA — add it to your phone's home screen to run it as a standalone app, with service-worker caching and an offline message queue (messages send once you reconnect)
-- Account management — password change and account deletion with safeguards
+- Installable PWA: add it to your phone's home screen to run it as a standalone app, with service-worker caching and an offline message queue (messages send once you reconnect)
+- Account management: password change and account deletion with safeguards
## Installation
-The intended way to deploy Backspace is the **interactive installer** — it
+The intended way to deploy Backspace is the **interactive installer**. It
configures everything (`.env`, secrets, HTTPS, optional voice) and brings the
stack up for you. It **auto-detects your environment** and picks one of three
-deployment modes — the default "All-in-One" (below) needs nothing but a host and
+deployment modes. The default "All-in-One" (below) needs nothing but a host and
a domain, but if ports 80/443 are already taken (an existing reverse proxy, a
tunnel, another app) the installer steers you to the right mode instead of
dead-ending. See [Deployment modes](#deployment-modes) for the full picture.
By default the installer **pulls a prebuilt multi-architecture image** from the
GitHub Container Registry (`linux/amd64` + `linux/arm64`), so weak or ARM boxes
-(a Raspberry Pi) skip the heavy local build — it falls back to building from
+(a Raspberry Pi) skip the heavy local build. It falls back to building from
source automatically if the image can't be pulled.
### Requirements
@@ -181,7 +181,7 @@ source automatically if the image can't be pulled.
- A **domain name** for your instance. In the default All-in-One mode it must
point at the host's public IP (Caddy obtains HTTPS certificates for it
automatically); behind your own reverse proxy or a tunnel it points at that
- edge instead — see [Deployment modes](#deployment-modes).
+ edge instead. See [Deployment modes](#deployment-modes).
- The ability to open the firewall ports in step 2 (All-in-One), or a reverse
proxy / tunnel already terminating HTTPS for you.
@@ -203,34 +203,34 @@ The installer walks you through everything interactively:
### 2. Open the firewall ports
-Open these on the host — and, if it's behind a router, port-forward them to the host:
+Open these on the host (and, if it's behind a router, port-forward them to the host):
| Port | Proto | When | Purpose |
|------|-------|------|---------|
-| `80` | TCP | **Always** | HTTP — Caddy's automatic-HTTPS (ACME) challenge + redirect to HTTPS |
-| `443` | TCP | **Always** | HTTPS — web app, REST API, WebSocket, and LiveKit signaling (proxied) |
-| `3478` | UDP | If voice enabled | TURN — NAT traversal for WebRTC |
+| `80` | TCP | **Always** | HTTP. Caddy's automatic-HTTPS (ACME) challenge + redirect to HTTPS |
+| `443` | TCP | **Always** | HTTPS. Web app, REST API, WebSocket, and LiveKit signaling (proxied) |
+| `3478` | UDP | If voice enabled | TURN. NAT traversal for WebRTC |
| `7881` | TCP | If voice enabled | WebRTC TCP fallback (clients that can't use UDP) |
| `50000–60000` | UDP | If voice enabled | WebRTC media (voice / video / screen-share streams) |
Without voice, you only need `80` and `443`. The voice ports are required only
-when you enable LiveKit. LiveKit's own signaling port (`7880`) stays internal —
-it's reverse-proxied through Caddy on `443`, so you do **not** forward it.
+when you enable LiveKit. LiveKit's own signaling port (`7880`) stays internal.
+It's reverse-proxied through Caddy on `443`, so you do **not** forward it.
> **Do this together with DNS, ideally before (or right after) running the
> installer.** Caddy gets your HTTPS certificate from Let's Encrypt the first
> time the stack starts, which requires your domain to resolve to this host
> **and** ports `80`/`443` reachable from the internet. If they aren't ready
-> yet, that's fine — Caddy keeps retrying, and HTTPS comes up automatically once
+> yet, that's fine. Caddy keeps retrying, and HTTPS comes up automatically once
> DNS and the ports are in place.
### 3. Create your admin account
Open `https://your-domain` and register. **The first account created becomes the
-instance admin** — there is no default username or password.
+instance admin**. There is no default username or password.
If the page doesn't load over HTTPS, it's almost always DNS or ports `80`/`443`
-not being reachable from outside — check `docker compose logs caddy` for
+not being reachable from outside. Check `docker compose logs caddy` for
certificate errors. (The installer's health check confirms the app is up
internally, not that the certificate was issued.)
@@ -244,7 +244,7 @@ backup/restore and image-pinning guide.
### Manual setup (advanced, optional)
The installer above is the supported path. If you'd rather configure everything
-by hand, you can skip it and drive Docker Compose directly — but then DNS,
+by hand, you can skip it and drive Docker Compose directly, but then DNS,
`.env`, secrets, voice config, and the same firewall ports from step 2 are your
responsibility:
@@ -265,7 +265,7 @@ The stack runs three services via Docker Compose:
|-------------|---------------------------------------------------|
| `backspace` | The app (API + WebSocket + built web client) on internal port `3000` |
| `caddy` | Reverse proxy with automatic HTTPS for your `DOMAIN` (ports `80`/`443`) |
-| `livekit` | Voice/video server — optional, enabled with `COMPOSE_PROFILES=voice` |
+| `livekit` | Voice/video server; optional, enabled with `COMPOSE_PROFILES=voice` |
## Deployment modes
@@ -276,15 +276,15 @@ non-interactive install (`DEPLOY_MODE=proxy ./install.sh`).
| Mode | When | HTTPS handled by | Voice |
|------|------|------------------|-------|
-| **`allinone`** (default) | Ports 80/443 are free and you have a domain | The bundled **Caddy** (automatic Let's Encrypt) | ✅ with UDP media ports open |
-| **`proxy`** | You already run a reverse proxy (nginx, Traefik, Caddy, Nginx Proxy Manager, SWAG…) | **Your** reverse proxy | ✅ if you also proxy `/livekit` and open the media ports |
-| **`tunnel`** | You expose the box through a tunnel (Cloudflare Tunnel, Tailscale…) | The **tunnel** provider | ❌ WebRTC/UDP can't traverse a tunnel |
+| **`allinone`** (default) | Ports 80/443 are free and you have a domain | The bundled **Caddy** (automatic Let's Encrypt) | Yes, with UDP media ports open |
+| **`proxy`** | You already run a reverse proxy (nginx, Traefik, Caddy, Nginx Proxy Manager, SWAG…) | **Your** reverse proxy | Yes, if you also proxy `/livekit` and open the media ports |
+| **`tunnel`** | You expose the box through a tunnel (Cloudflare Tunnel, Tailscale…) | The **tunnel** provider | No, WebRTC/UDP can't traverse a tunnel |
In `proxy` and `tunnel` mode the bundled Caddy is **not** started; instead the app
-is published on **`127.0.0.1:APP_PORT`** (loopback only — never exposed directly)
+is published on **`127.0.0.1:APP_PORT`** (loopback only, never exposed directly)
for your proxy or tunnel to forward to. This is driven by a small overlay,
`docker-compose.proxy.yml`, which the installer wires in for you by setting
-`COMPOSE_FILE=docker-compose.yml:docker-compose.proxy.yml` in `.env` — so every
+`COMPOSE_FILE=docker-compose.yml:docker-compose.proxy.yml` in `.env`, so every
later `docker compose …` command in the directory keeps working with no `-f`
flags. The installer auto-picks a free `APP_PORT` (3000/8080 are often taken);
override it with `APP_PORT=…`.
@@ -292,7 +292,7 @@ override it with `APP_PORT=…`.
The installer prints ready-to-paste config for your mode at the end. The
canonical snippets are below.
-### Mode 2 — behind your own reverse proxy
+### Mode 2: behind your own reverse proxy
The app answers plain HTTP on `127.0.0.1:APP_PORT`; your proxy terminates TLS and
forwards to it. Every snippet already includes the three things people get wrong:
@@ -302,7 +302,7 @@ scheme/IP), and a **body-size limit** matching `MAX_UPLOAD_SIZE` (default 100 MB
Replace `chat.example.com` and `8080` with your domain and `APP_PORT`.
-**nginx** — the `map` goes in `http { }` once; the `server` block per site:
+**nginx.** The `map` goes in `http { }` once; the `server` block per site:
```nginx
map $http_upgrade $connection_upgrade { default upgrade; '' close; }
@@ -330,7 +330,7 @@ server {
proxy_send_timeout 3600s;
}
- # Voice only — forward LiveKit signaling (strips the /livekit prefix):
+ # Voice only: forward LiveKit signaling (strips the /livekit prefix):
# location /livekit/ {
# proxy_pass http://127.0.0.1:7880/;
# proxy_http_version 1.1;
@@ -341,7 +341,7 @@ server {
}
```
-**Caddy** (if you run your own — it handles WebSocket and `X-Forwarded-*` itself):
+**Caddy** (if you run your own; it handles WebSocket and `X-Forwarded-*` itself):
```caddy
chat.example.com {
@@ -354,7 +354,7 @@ chat.example.com {
}
```
-**Traefik** (file provider — Traefik handles WebSocket automatically):
+**Traefik** (file provider; Traefik handles WebSocket automatically):
```yaml
http:
@@ -369,7 +369,7 @@ http:
loadBalancer:
servers:
- url: "http://127.0.0.1:8080"
- # Voice only — add a higher-priority router + stripPrefix middleware for
+ # Voice only: add a higher-priority router + stripPrefix middleware for
# PathPrefix(`/livekit`) → http://127.0.0.1:7880.
```
@@ -382,9 +382,9 @@ by hand. In **Nginx Proxy Manager**, add a **Proxy Host**:
|-------|-------|
| **Domain Names** | `chat.example.com` |
| **Scheme** | `http` |
-| **Forward Hostname / IP** | `127.0.0.1` — but **if NPM runs in Docker**, `127.0.0.1` is NPM's *own* container. Use the host's LAN IP, or `host.docker.internal` with `extra_hosts: ["host.docker.internal:host-gateway"]` on the NPM container. |
+| **Forward Hostname / IP** | `127.0.0.1`, but **if NPM runs in Docker**, `127.0.0.1` is NPM's *own* container. Use the host's LAN IP, or `host.docker.internal` with `extra_hosts: ["host.docker.internal:host-gateway"]` on the NPM container. |
| **Forward Port** | your `APP_PORT` (e.g. `8080`) |
-| **Websockets Support** | **ON** (required — chat/live events break without it) |
+| **Websockets Support** | **ON** (required; chat/live events break without it) |
| **Block Common Exploits** | fine to leave on |
| **SSL tab** | request a Let's Encrypt cert and enable **Force SSL** |
| **Advanced tab** | add `client_max_body_size 100m;` (match `MAX_UPLOAD_SIZE`) |
@@ -392,7 +392,7 @@ by hand. In **Nginx Proxy Manager**, add a **Proxy Host**:
The same three ideas apply to any GUI proxy: forward to the app's host+port,
enable WebSocket support, and raise the request-body limit.
-### Mode 3 — behind a tunnel (Cloudflare, Tailscale…)
+### Mode 3: behind a tunnel (Cloudflare, Tailscale)
Same loopback publish as Mode 2, but the tunnel daemon on the host reaches
`127.0.0.1:APP_PORT` and no inbound ports are opened at all. For **Cloudflare
@@ -419,33 +419,33 @@ Two tunnel-specific caveats, both handled by the installer:
the 100 MB default would let large uploads fail *at the edge*. In `tunnel` mode
the installer sets `MAX_UPLOAD_SIZE=94371840` (90 MB) with headroom. Don't raise
it back above ~100 MB behind Cloudflare.
-- **No voice.** Voice/video is **WebRTC over UDP**, which a tunnel can't carry — so
+- **No voice.** Voice/video is **WebRTC over UDP**, which a tunnel can't carry, so
it's disabled in `tunnel` mode. If you need voice, use Mode 2 (reverse proxy)
with the media ports opened, or All-in-One.
### Voice per mode
-Voice/video (LiveKit) needs its **UDP media ports** reachable from clients —
-these carry the actual audio/video and never pass through your HTTP proxy or
+Voice/video (LiveKit) needs its **UDP media ports** reachable from clients.
+These carry the actual audio/video and never pass through your HTTP proxy or
tunnel:
| Port | Proto | Purpose |
|------|-------|---------|
-| `3478` | UDP | TURN — WebRTC NAT traversal |
+| `3478` | UDP | TURN. WebRTC NAT traversal |
| `7881` | TCP | WebRTC TCP fallback |
| `50000–60000` | UDP | WebRTC media (voice / video / screen-share) |
-- **All-in-One** — voice works once those ports are open/forwarded. LiveKit
+- **All-in-One.** Voice works once those ports are open/forwarded. LiveKit
*signaling* is proxied through Caddy on 443 (`/livekit`); port `7880` stays
internal, never forwarded.
-- **Reverse proxy** — you must **also** route `/livekit` to `127.0.0.1:7880` (see
+- **Reverse proxy.** You must **also** route `/livekit` to `127.0.0.1:7880` (see
the commented lines in the snippets) **and** open the media ports above.
-- **Tunnel** — voice does **not** work (UDP can't traverse the tunnel). This is a
+- **Tunnel.** Voice does **not** work (UDP can't traverse the tunnel). This is a
known, unavoidable limitation, not a misconfiguration.
### Updating a running instance
-Back up first — the app auto-snapshots the SQLite DB, and you can take one on
+Back up first. The app auto-snapshots the SQLite DB, and you can take one on
demand with `./backup.sh` (see [`docs/systems/deployment.md`](docs/systems/deployment.md)).
Then, from the install directory:
@@ -460,12 +460,12 @@ docker compose up -d --build
```
Because `COMPOSE_FILE` lives in `.env`, these commands automatically use the
-right compose files in every mode — no `-f` flags to remember. A redeploy
+right compose files in every mode, with no `-f` flags to remember. A redeploy
briefly restarts the `backspace` container (clients reconnect automatically).
## Development
-Requirements: **Node.js 20 (LTS)** and **pnpm 10** — both are pinned (`.nvmrc` +
+Requirements: **Node.js 20 (LTS)** and **pnpm 10**, both pinned (`.nvmrc` plus
the `packageManager` field), so `nvm use` and Corepack select the right versions
automatically. Newer Node majors are untested; the Docker image always builds on
Node 20 regardless of your host.
@@ -478,11 +478,11 @@ pnpm dev # API server on :3005, Vite dev server on :5173
> **Server/web only?** `pnpm install` also builds the desktop app's native
> keyboard-hook module (`uiohook-napi`), which needs a C++ toolchain
-> (`make`, `g++`, `python3`). If those are missing it now **warns and continues** —
-> the server and web client don't need it. Install a build toolchain
+> (`make`, `g++`, `python3`). If those are missing it now **warns and continues**,
+> and the server and web client don't need it. Install a build toolchain
> (Debian/Ubuntu: `sudo apt install build-essential python3`) only if you're
> building the **desktop** app. And to *self-host*, use the Docker installer
-> above — it never touches the desktop package.
+> above; it never touches the desktop package.
Run the halves separately if you prefer:
@@ -506,22 +506,22 @@ The most important:
| Variable | Required | Default | Description |
|----------------------|----------|-------------|-------------|
-| `DOMAIN` | yes | — | Public domain name of your instance |
-| `JWT_SECRET` | yes | — | Auth signing secret, **min 32 chars** (`openssl rand -hex 32`) |
-| `DEPLOY_MODE` | no | `allinone` | `allinone` \| `proxy` \| `tunnel` — see [Deployment modes](#deployment-modes) |
+| `DOMAIN` | yes | none | Public domain name of your instance |
+| `JWT_SECRET` | yes | none | Auth signing secret, **min 32 chars** (`openssl rand -hex 32`) |
+| `DEPLOY_MODE` | no | `allinone` | `allinone` \| `proxy` \| `tunnel`, see [Deployment modes](#deployment-modes) |
| `APP_PORT` | no | auto | `proxy`/`tunnel` only: host loopback port the app is published on |
| `PORT` | no | `3000` | App listen port (behind Caddy in Docker) |
| `HOST` | no | `0.0.0.0` | Bind address |
| `REGISTRATION_OPEN` | no | `true` | Set `false` to close signups after setup |
| `MAX_UPLOAD_SIZE` | no | `104857600` | Max upload size in bytes (100 MB; 90 MB in `tunnel` mode) |
| `BACKSPACE_IMAGE` / `BACKSPACE_IMAGE_TAG` | no | `ghcr.io/thezwiss/backspace` / `latest` | Prebuilt image to pull; pin a tag or point at your fork's registry |
-| `LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | no | — | Enable voice/video |
-| `COMPOSE_PROFILES` | no | — | Set to `voice` to start the bundled LiveKit service |
+| `LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | no | none | Enable voice/video |
+| `COMPOSE_PROFILES` | no | none | Set to `voice` to start the bundled LiveKit service |
## Voice & Video
Voice, video, and screen sharing require a [LiveKit](https://livekit.io/) server.
-The Docker Compose file bundles one — enable it by setting these in `.env`:
+The Docker Compose file bundles one. Enable it by setting these in `.env`:
```bash
COMPOSE_PROFILES=voice
@@ -531,10 +531,10 @@ LIVEKIT_API_SECRET=your-api-secret
```
Enabling voice also requires opening the WebRTC ports (`3478/UDP`, `7881/TCP`,
-`50000–60000/UDP`) — see [Open the firewall ports](#2-open-the-firewall-ports).
+`50000–60000/UDP`). See [Open the firewall ports](#2-open-the-firewall-ports).
-Without LiveKit configured, everything else — text, federation, DMs, uploads,
-search — works fully; only voice/video channels won't connect.
+Without LiveKit configured, everything else works fully (text, federation, DMs,
+uploads, search); only voice/video channels won't connect.
## Federation
@@ -558,11 +558,11 @@ Grab the installer for your platform from the
| Platform | File | Notes |
|----------|------|-------|
-| Windows | `Backspace-
-A voice channel in full swing — camera tiles alongside live screen-shares, each with its own resolution / frame-rate label.
+A voice channel in full swing. Camera tiles alongside live screen-shares, each with its own resolution and frame-rate label.
@@ -67,31 +67,31 @@ You own the server, the data, and the network it federates into.