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. Running a cluster instead of a single machine? See the Kubernetes or OpenShift guide.

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 your TheoWorks account (Google or email) 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:

bash

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 identity-enforcing edge, with your edge in front (your GitLab sign-in remains the access control either way). TheoWorks does not implement single sign-on (SSO/SAML) itself — that is not available as a built-in capability; the reverse-proxy placement above is the supported way to sit behind your own SSO-enforcing edge today.

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 instead of the guided launcher? A manual Docker Compose deployment against the same app image is also supported, behind your own GitLab and TLS.

Updates and backup

The launcher Dashboard has a Check for updates control; when a newer app image is available, Update and restart pulls it and restarts the server — your settings are snapshotted first, so the change is reversible. 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.