From nothing to 20 verified episodes

1. 1

   Install and sign up

   During the private beta the CLI is a file we send you with your invite: one package, the CLI and the TypeScript SDK together. Sign-up asks for the invite code and stores your API key for you. A key you already have is read from an environment variable or stdin, never argv: a key on a command line lands in shell history and every process listing.

   Terminal

   shasum -a 256 promigence-<version>.tgz   # or sha256sum; must match the sha256 we sent you
   npm i -g ./promigence-<version>.tgz
   promigence signup                        # asks for your invite code
   promigence doctor
   

   Language: bash

2. 2

   Build a verified snapshot

   Start from an image with git and your toolchain, clone your repository at a pinned commit, add the setup steps and a verify command. If verify does not exit zero, nothing is stored and nothing is charged; a build that verifies costs $1. Pin the commit: a snapshot built from a moving ref is not reproducible.

   Terminal

   promigence snapshot create \
     --image node:22 \
     --setup "git clone https://github.com/<you>/<repo> /work/repo && git -C /work/repo checkout <40-char sha>" \
     --setup "cd /work/repo && npm ci" \
     --verify "cd /work/repo && npm test" \
     --tier small --alias myapp --wait --wait-timeout 10m
   

   Language: bash

3. 3

   Price the run before you start it

   A quote is a ceiling, not an estimate: every sandbox running for its whole timeout. --cap enforces it: a run that would exceed the cap is refused outright, before anything starts.

   Terminal

   promigence run quote --snapshot myapp --count 20 --timeout 15m
   # → 20 × small (2 vCPU, 4 GiB) for up to 15 minutes each
   # → max cost  $0.83
   

   Language: bash

4. 4

   Fork, execute, report

   One command forks N environments, runs your command in each, and prints the validity report. --verify-each re-runs verify inside every fork first, which is worth it on a run you intend to publish. In the private beta, 20 sandboxes run at once.

   Terminal

   promigence run \
     --snapshot myapp \
     --count 20 --cap 1 \
     --verify-each \
     -- sh -c "cd /work/repo && npm test"
   
   # → the validity report: completed, task failures, environment failures, and the cost
   

   Language: bash

5. 5

   Read the report, open a failure

   A task failure is yours: your command exited non-zero. An environment failure is ours: it never counts against your agent, and it is not billed when our side can show it was ours. An environment failure can be replayed, as a new sandbox billed like any other, and any failure can be reproduced from the command the report prints with --repro.

   Terminal

   promigence run report <run_id> --sandboxes failed
   promigence run report <run_id> --sandbox <sid> --repro   # the command that reproduces it
   

   Language: bash

Next

• Every command and flag
• Do the same thing from TypeScript
• What each error code means and whether it was billed