Self-hosting

Self-hosted TheoWorks runs on your own machine or server, against your own Git repository, cloud-free. This section covers install, updates, and licensing at a practical level.

Install with the launcher

Download the launcher from theoworks.io/download — sign in with GitLab and the page hands you the archive for your OS (Linux, macOS, or Windows). Extract it and run the guided launcher:

• Windows — unzip, then double-click Start TheoWorks.cmd.
• macOS / Linux — extract the archive and run the start script:

tar -xzf <archive>.tar.gz
./start-theoworks.sh

The launcher opens a setup wizard in your browser, checks for Docker, then asks whether you want a Quick start (local, single-user — see the Quickstart) or to set up team access now.

Team access and exposure

Choosing Set up team access walks you through a networked deployment your colleagues can reach and sign in to. The wizard asks how people will reach this server and tailors the config (and the exact OAuth redirect URI) to it:

• Internal network (LAN) — an internal hostname you own; self-signed or your internal-CA certificate, no public DNS.
• Public address (automatic HTTPS) — a public DNS name that resolves to this box; the bundled proxy provisions a trusted certificate automatically.
• Behind your reverse proxy — your edge terminates TLS and forwards to TheoWorks; the wizard emits a proxy snippet. This is also how you place TheoWorks behind an SSO/identity-enforcing edge — the same reverse-proxy placement, with your edge in front (your GitLab sign-in remains the access control either way).

Team sign-in is your own GitLab. The wizard has you register a one-time GitLab OAuth application (it shows the exact redirect URI to paste — the #1 cause of sign-in failure — plus the api scope), then you paste back the Application ID and Secret and can Test connection before anything is written. It reviews the exact config (secrets masked) before it writes and starts the stack. The first person to sign in becomes the maintainer.

Choose the exposure that matches your security posture: keep it local while evaluating, and put it behind your own network controls when you share it.

Updates and backup

Updates are governed so an upgrade is deliberate, not surprising. Because your project is plain RST in Git, your backup is your repository — commit and push, and your content is safe independent of the TheoWorks install. Teardown is safe: removing TheoWorks never removes your repo.

Licensing and seats

The free tier has a soft seat cap and needs no license key — the launcher connects automatically. Pro and Enterprise tiers add seats and support. See the pricing page on the marketing site for current tiers.