Verifying your work — th run
th run takes the diff sitting in your working tree, applies it to a clean
clone of the target repository, and runs the project's own install and test
commands inside a container. You get a verdict, and a preview URL you can open
to read the whole run.
It is for the gap between "the tests pass on my machine" and "I submitted it and waited." You find out before the founder does.
What you need
Docker running, and network access for the first clone of the target. Nothing else — the engine ships inside the CLI.
The short version
th run --claim <id> --target https://github.com/koajs/koa.git --sha <40-hex>
Run it again and again while you work; add --watch to re-run on every save.
Defaults live in .th-run.json in your checkout, so a claim you run repeatedly
needs no flags at all. Every flag overrides the file.
Options
| Flag | What it does |
|---|---|
--claim <id> |
The claim this work belongs to |
--target <git-url> |
Repository the work is verified against |
--sha <40-hex> |
The commit your diff applies on top of |
--slice <a,b,c> |
Files this claim shares. A diff touching anything else is refused before any container starts |
--local <dir> |
Checkout to read the working diff from (default: the current directory) |
--watch |
Re-run whenever a file in the checkout changes |
--keep <seconds> |
Hold the preview open this long (default: until you press Ctrl-C) |
--no-preview |
Skip the preview URL |
--json |
Print the result as JSON instead of a report |
--test-command <cmd> |
Override the derived test command. The override is recorded in the result |
--placement <kind> |
Where the run happens. Today: local-docker. See Where it runs |
How a run is fenced
A run is two steps, and they are fenced differently on purpose.
Install gets a network, through one door. Dependencies have to come from somewhere, so the install step reaches the outside only through an allowlisting proxy on its own internal network. There is no route around it.
Tests get no network at all. The test step runs with networking switched off entirely — no interface, no proxy, nothing to reach. A test suite that quietly depends on a live service fails here, which is the point: so does the founder's CI.
The container drops all capabilities, forbids privilege escalation, and caps process count. The repository's own code never runs anywhere else.
The preview
Unless you pass --no-preview, a run ends with a URL. Opening it shows the
same result the terminal printed — the verdict, the test output tail, and what
was actually run.
The preview binds to loopback only. It is reachable from your machine and
nowhere else, and it stops when you press Ctrl-C or when --keep runs out.
Expiry and revocation beyond that are not built yet.
Where it runs
Today every run happens on your machine, in your Docker daemon. That is
what --placement local-docker means, and it is the default.
--placement hosted is declared but refuses to run. It names a hosted pool
where verification would happen on neutral ground — neither you nor the founder
operating the machine — which is worth having and is being built. Until it is
finished, asking for it refuses — before your diff is read and before anything
is cloned — because a run that quietly happened on your own laptop and was
reported as neutral would be a worse answer than no answer.
The refusal exits 2, not 1. In this command 1 means your tests ran and failed; 2 means we declined to run them. A script can tell the two apart, and nothing we refuse to do will ever be reported as a fault in your work.
What a result is, and is not
A run tells you what the project's own tests did, on a clean tree, with your diff applied. That is useful and it is checkable.
It is not an attestation that anything ran on hardware anyone can vouch for. The result records this about itself in plain terms rather than implying otherwise, and it will keep doing so until the hosted venue exists to make a stronger statement true.
Where this fits
th run is the step before claim submit. Run it
until it is green, then submit. On a founder posting you can read the founder's
own verdict afterwards with claim runs <id>.