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.
You land directly in a project. The demo opens a curated ASPICE sample project — no picker, nothing to set up. Edit anything you like; a Reset demo control restores the sample if you want to start over.
Try it out. Browse the tree on the left, read a need in the centre, and switch the toolbar between Read, Edit, and .rst to make a change, then click Build & validate. See Using the editor for the full tour.

Self-hosted quickstart

Download the launcher. Go to theoworks.io/download, sign in with your TheoWorks account (Google or email), 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. 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. It first runs a Docker check, then asks What do you want to do?
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.

Tip

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).

The web demo itself is ready-to-try only — one curated sample project, no project picker. To start your own project on the web, sign in to the hosted app from theoworks.io and choose New project to pick a template (see Project setup → Start a new project). 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 → Bring an existing sphinx-needs project.

Note

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.