Install guide

Choose how you run TheoWorks

Four channels — pick the one that fits how you (or your team) will use it.

Web demo

Pick this if you want to try TheoWorks with nothing installed.

Go to theoworks.io and click Try now → Web demo. You land at try.theoworks.io with a sample project already open.
Your edits stay in your browser — nothing to install, nothing to sign in to.

VS Code extension — "TheoWorks IDE"

Pick this if you already live in VS Code and want the editor + live preview inline, no separate app to run.

Install TheoWorks IDE from the VS Code Marketplace.
Open a folder containing a sphinx-needs project (or an empty folder to start fresh).
Sign in when prompted.

Self-hosted server (launcher)

Pick this if your data must stay on your own infrastructure, or your team needs a shared server everyone signs in to.

Go to theoworks.io/download and sign in with your TheoWorks account (Google or email).
Pick your platform and download the launcher archive for it (Linux, macOS, or Windows).
Extract it and run the guided launcher. On Windows, unzip and double-click Start TheoWorks.cmd. On macOS / Linux, extract the archive and run the start script:
bash
```
tar -xzf <archive>.tar.gz
./start-theoworks.sh
```
A setup wizard opens in your browser. Choose Quick start to try it locally, or Set up team access for a shared server — see Self-hosting for the full walkthrough (team access, exposure modes, updates).

Your own cluster (Kubernetes or OpenShift)

Pick this if your team runs on a Kubernetes cluster instead of a single machine. Red Hat OpenShift cluster? Use the OpenShift guide. Any other Kubernetes cluster? Use the Kubernetes guide.

Already have a sphinx-needs repo?

TheoWorks reads your project's own schema and needs — it does not scaffold into or rewrite an existing repo just to open it. See Project setup → Bring an existing sphinx-needs project for what your repo and its CI need to provide.

Verify the install worked

The editor opens your repo without an error.
Your existing needs render in the tree and content panes.
Editing and saving a need round-trips to a clean, minimal RST diff.