Self-hosting

Self-hosting Tabs & Spaces

Tabs & Spaces is free to run yourself. A deployment is one installation: your server (or the cloud services you choose), your domain, your data. People sign up on it and work in workspaces, each with its own spaces, agents and data.

This section covers:

1. Install (this page): one server with Docker Compose.
2. First-run setup: naming the deployment and creating the first admin account and workspace.
3. Managed services: using a hosted database, Redis, storage and email instead, and running on Fly.io.
4. Running your deployment: agents, billing, support, upgrades, backups and health.

#What it's made of

A deployment runs two containers:

• The API, which keeps the data and does the work.
• The web server (Caddy), which serves the app, forwards /api to the API (including its real-time connection), and gets HTTPS certificates for you.

They need a few services:

#Requirements

• Docker with Compose v2.20 or later.
• Memory: about 2 GB for the app, MongoDB and storage. Add about 1.5 GB to run the agents' Gateway.
• For a public server: a domain pointing at the machine, with ports 80 and 443 open.
• The repository, which has everything under deploy/:

#Install

cd deploy
./setup.sh --domain chat.example.com   # or just ./setup.sh to try it on this machine
docker compose up -d

setup.sh writes .env, readable only by you. It holds generated secrets, the bundled services to run, and your address. At the end, it prints the first-run setup link: open it to set up the deployment.

Its options:

Without --domain, the app is at http://localhost, and email goes to the bundled Mailpit, which only catches it: read it at http://localhost:8025. With --domain, set the SMTP_* settings in .env to a real email service before people sign up.

#Choosing what runs here

COMPOSE_PROFILES in .env lists the bundled services to run. To use your own service instead, remove its profile, set its settings, and run docker compose up -d.

Hosted services need a few things set up right, such as a database user that may delete databases, and Redis that never evicts: Managed services goes through each one.

Workspaces can also keep their data in their own MongoDB and bucket, chosen when they're created. A deployment admin can turn that off in Deployment settings. If those databases or buckets are on your private network, set WORKSPACE_INFRASTRUCTURE_PRIVATE_NETWORKS=true.

#Behind your own proxy

Set SITE_ADDRESS=:80, choose a port with HTTP_PORT, and set PUBLIC_URL to the address people use, e.g. https://chat.example.com. Your proxy must:

• forward everything to that port, including WebSocket upgrades on /api/ws;
• allow large request bodies: attachments up to ATTACHMENT_MAX_MB, Docs files up to DOCS_MAX_MB, imports up to IMPORT_MAX_MB;
• send X-Forwarded-For, so sign-ins are recorded with the visitor's address. The web server trusts it from private networks.