Project & workspace

Two words, two scopes, and they are easy to confuse.

• A project is what you open in the desktop app: a folder on your machine holding collections, chains, auth providers, and the rest.
• A workspace is the unit of sharing and sync in the paid cloud tier.

Locally, you only ever deal with projects. The cloud tier is not available to sign up for at v0.1.0-preview.9 — see Local & cloud.

A project

Point Tinspec at a folder and that folder is the project. Everything is plain YAML, laid out as in Project layout, and meant to be committed alongside the service it tests.

You can also create a folderless project, which writes nothing to disk. It is fine for a scratch session, but run history, the spec cache, and endpoint overlays all need a folder, so they are session-only there.

Files are the source of truth

This is a hard rule, not a preference:

The YAML files are authoritative. Collections, chains, auth definitions, providers, route matchers, overlays — all of them are files, all of them diff cleanly, all of them are yours.

SQLite is a rebuildable cache. Each project folder gets a .tinspec/tinspec.db holding run history, the spec cache, and search indexes. Delete it and everything is rebuilt by re-reading the files. The only thing genuinely lost is run history.

Secrets are in neither. Not in the files, not in the database. They live in your OS keychain or a machine-local encrypted store, and the files reference them by name.

The consequence is that your API tests are just source code. They live in the repository of the service they test, they review in a merge request, they branch when the API branches.

What a workspace adds

In the cloud tier a workspace is what a team shares. Sync is server-as-source-of-truth, versioned whole-document push and pull: each document carries a version, a push from a stale base returns a conflict rather than overwriting, and a pull never silently overwrites a local file you have edited since it last synced — that is a conflict too, which you resolve by taking remote, keeping local, or deleting.

Secrets never sync. Auth definitions reference secret names; the values stay on the machine that holds them.

The desktop app remains fully usable offline with no account, and nothing in these docs outside the Local & cloud page requires one.