Quickstart
Two short paths, one per flavor. Pick yours with the tabs below; the shared concepts (needs, links, the git round-trip) are the same either way.
Web demo quickstart
- Open the web demo. Go to theoworks.io and click Try now. Nothing to install.
- Pick a starting project. Choose the sample project to explore a pre-populated set of needs, or a blank project to start from scratch. The sample is the fastest way to see typed needs and traceability in action.
- Land in the editor. You are now in the three-pane editor. Browse the tree on the left, read a need in the center, and toggle read/edit to make a change. See Using the editor for the full tour.
Self-hosted quickstart
-
Download the launcher. Go to theoworks.io/download, sign in with GitLab, and download the guided launcher archive for your OS — the page auto-detects Linux, macOS, or Windows. The free tier needs no license key. (TheoWorks runs in Docker, so make sure a container runtime is installed; the wizard checks for it in the next step.)
-
Extract it and run the launcher. Unpack the archive and start the guided launcher — no terminal wrangling:
- Windows — unzip, then double-click
Start TheoWorks.cmd. - macOS / Linux —
tar -xzf <archive>.tar.gz && ./start-theoworks.sh.
A setup wizard opens in your browser. It first runs a Docker check, then asks What do you want to do?
- Windows — unzip, then double-click
-
Choose Quick start → open the editor. Pick Quick start (the recommended path — no GitLab, no sign-in). The launcher writes a local-mode config, pulls the app image, brings the stack up, and shows an Open the editor button. Click it and you land in the editor with a sample project to explore. Everything runs on your machine.
Ready to let colleagues sign in? Re-run the wizard (or use the launcher Dashboard's Set up team sign-in) and choose Set up team access — see Self-hosting for the GitLab OAuth walkthrough.
Your first project
However you got here, creating a project is the same idea: a project is a
sphinx-needs docs directory with a conf.py (its schema) and RST files (its
needs).
Choose New project and pick a template (see Project setup → Templates & packs). TheoWorks scaffolds a buildable project you can start editing immediately.
Quick start already gave you a working project — the launcher seeds a
sample sphinx-needs project (its own conf.py schema + a docs tree of RST)
the first time the editor opens. Explore that to learn the model.
When you want to edit your own content, connect a repository: run the wizard's Set up team access branch (or the Dashboard's Set up team sign-in), point it at your GitLab, and TheoWorks reads the schema and needs straight from the repo you connect. See Project setup → Connecting an existing repo.
Scripting an install? The launcher binary also exposes a non-interactive
theoworks setup (config generator) — run ./theoworks setup --help. A repo
you connect keeps its own conf.py (the schema) and RST docs directory either
way.
These web/self-hosted variants are the same guide, filtered by the flavor tabs (and the left-nav flavor toggle). Shared concepts are written once; only the divergent steps diverge.