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.

Note

This is the depth material for the self-hosted flavor. If you only want to try the editor, the Quickstart web-demo path is faster.

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 — 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.
Behind your SSO gateway — the reverse-proxy placement plus your edge enforcing SSO in front.

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.

Note

Prefer to run the containers yourself? A manual docker compose bundle (infra/compose/) deploys the same image behind your own GitLab and TLS — see the repository's docs/self-hosted-install.md corporate install guide. The launcher above is the guided path; the Compose bundle is the manual equivalent.

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.

Roadmap, not shipped

Fully air-gapped operation and single sign-on (SSO) are on the roadmap and are not documented here as shipping capabilities. If you have a strict air-gap or SSO requirement today, treat it as a forward-looking item, not a current feature.