ProveCommands
`poisson-prove where`
Says where sweeps of the spec in this folder run, and whether that is ready on this machine: this
machine, Modal, or your own cloud account. With local, modal or cloud it sets it, by writing
the matching table into ./prove.toml.
A spec runs where its table says. A [cloud] table means your cloud account, a [modal] table
means Modal, and neither means this machine. poisson-prove sweep with no --backend runs there.
Backends says what each choice needs and does.
poisson-prove where --helpOutput49 lines
usage: poisson-prove where [-h] [--spec PATH] [--cloud NAME] [--region REGION] [--machine-type TYPE] [--nodes N] [--max-vcpus N] [--stop-cost USD] [--max-cost USD] [--yes] [--json] [--store PATH] [--plain] [--debug] [{local,modal,cloud}]
Say where sweeps of ./prove.toml run (this machine, Modal or your own cloudaccount) and whether that is ready on this machine; or, with local, modal orcloud, set it, by writing the matching table into the spec and nothing else.In a terminal it asks for what no option gives and the spec does not hold;--yes takes the defaults instead. It asks for no secret and signs in tonothing: a cloud is reached through that cloud's own sign-in on this machine.
positional arguments: {local,modal,cloud} where sweeps run from now on (default: only say where they run)
options: -h, --help show this help message and exit --spec PATH the sweep spec to read or change (default: ./prove.toml) --cloud NAME with cloud: which cloud (default: aws, the one offered) --region REGION with cloud: where the nodes start (default: us-east-2) --machine-type TYPE with cloud: the nodes' machine type (default: m7i.2xlarge) --nodes N with cloud: how many nodes Prove starts (default: 4) --max-vcpus N with cloud: the vCPU ceiling (default: the nodes times the machine's vCPUs) --stop-cost USD with cloud: the spend at which Prove stops the sweep (default: 2) --max-cost USD with cloud or modal: the estimate above which a sweep is refused (default: 3 on a cloud account, no cap on Modal) --yes take the default for what no option gives, and ask nothing (default: ask in a terminal) --json print where sweeps run as one JSON document instead of text --store PATH the store folder (default: $POISSON_PROVE_STORE when set, else ./prove-runs) --plain print plain text, as a pipe gets it, on a terminal too (default: pretty on a terminal, plain otherwise) --debug also print the traceback of an unexpected failure
examples: poisson-prove where poisson-prove where cloud poisson-prove where cloud --region us-east-2 --nodes 4 --yes poisson-prove where modal --max-cost 5 poisson-prove where localOptions
Section titled “Options”local,modalorcloud, the one positional word, sets where sweeps run from now on.poisson-prove where localtakes the table out of the spec.poisson-prove where modalwrites a[modal]table.poisson-prove where cloudwrites a[cloud]table. With no word,whereonly says where sweeps run, and writes nothing.--spec PATHnames the spec to read or change, when it is not./prove.toml.--cloud NAMEnames the cloud. This release offersaws. Google Cloud and Azure are refused as not yet supported.--region REGIONis where the nodes start,us-east-2by default.--machine-type TYPEis the nodes’ machine type,m7i.2xlargeby default. Both come from Prove’s price table, which The sweep spec lists.--nodes Nis how many nodes Prove starts, 4 by default.--max-vcpus Nis the vCPU ceiling: a plan whose nodes need more is refused. Without it the ceiling is the nodes times the machine’s vCPUs.--stop-cost USDis the spend at which Prove stops the sweep, $2 by default.--max-cost USDis the estimate above which a sweep is refused, $3 by default on a cloud account. Withmodalit sets the Modal table’s cap, which has no default, and the table then also getsest_seconds_per_episode = 1.0.--yestakes the default for everything no option gives, and asks nothing.--jsonprints the answer as one JSON document,poisson-prove.where/1.--store PATHis the store folder.wherereads it only to name the run of a cluster an earlier sweep left.--plainprints plain text on a terminal too.--debugadds the traceback of an unexpected failure.
The options from --cloud to --stop-cost go with cloud alone, and --max-cost with cloud
or modal. Given with another word, each is a usage error, exit 2.
What is asked. In a terminal, where cloud asks for each value that no option gives and the
spec does not already hold, one question a line, with its default in brackets. Enter takes the
default. where modal asks for the cap. With --yes nothing is asked and the defaults stand. Off
a terminal with no --yes, the first missing value is refused, naming its option.
What is kept. A table already in the spec keeps every value no option changes, so
poisson-prove where cloud --nodes 8 changes the nodes and nothing else. Your comments, spacing
and key order inside the table stay too. The one exception is a table holding a value written over
several lines: where then writes the table whole, and comments inside it go.
Examples
Section titled “Examples”The quickstart’s spec holds neither table, so it runs on this machine:
poisson-prove whereOutput2 lines
where this machine next: poisson-prove sweepwhere local sets that, taking a [modal] or [cloud] table out when one is there. The same
answer as JSON, for a script:
poisson-prove where localOutput2 lines
where this machine next: poisson-prove sweeppoisson-prove where --jsonOutput10 lines
{ "schema": "poisson-prove.where/1", "verdict": "where", "sentence": "this machine", "runs_on": "local", "spec": "prove.toml", "ready": true, "checks": [], "next": ["poisson-prove sweep"]}ready is false when a check failed. checks holds each check’s label, value, ok and
next, the one command that fixes a failed check or null.
Your cloud account
Section titled “Your cloud account”where cloud writes the [cloud] table and checks that this machine can use the account: the
extra, the AWS CLI, the sign-in, the region and machine type, and the vCPU quota. The account is
shown masked. The first line is the sentence bare where prints, shown in the block after this
one:
poisson-prove where cloud --region us-east-2 --nodes 4 --yesOutput4 lines
… signed in AWS 6030…4933 wrote [cloud] into prove.toml next: poisson-prove sweep --dry-runThe table it writes for those answers is the one below. ledger and est_seconds_per_episode
are not asked for. The estimate in the plan follows est_seconds_per_episode, the seconds one
rollout takes, so set it from a run on this machine before you trust the estimate.
[cloud]provider = "aws"region = "us-east-2"machine_type = "m7i.2xlarge"nodes = 4max_vcpus = 32ledger = "cloud-ledger.jsonl"stop_cost = 2.0max_cost = 3.0est_seconds_per_episode = 1.0Bare where then gives the answer and whether it is ready, and next: is the sweep:
poisson-prove whereOutput3 lines
where your AWS account, us-east-2, 4 × m7i.2xlarge; signed in, ready signed in AWS 6030…4933 next: poisson-prove sweepA check that fails does not stop the table being written: you can fix it later. where still
exits 0, the sentence says what is not ready, and next:, when one command fixes it, is that
command. A sweep is refused until the check passes. On a machine that has not signed in:
poisson-prove whereOutput2 lines
where your AWS account, us-east-2, 4 × m7i.2xlarge; not ready: this machine is not signed in to AWS next: aws loginA value Prove cannot use on any machine is refused, and nothing is written. That covers a cloud this release does not offer, a region or machine type outside the price table, and a number out of its range:
poisson-prove where cloud --cloud gcp --yes # exits 1Output1 line
error: Google Cloud is not yet supported by Prove; AWS iswhere modal writes the [modal] table and asks Modal’s own client whether this machine is
signed in. It does not read the token and never shows it. When the machine is not signed in, the
sentence says so and next: is modal setup:
poisson-prove where modal --yesOutput4 lines
where Modal; signed in, ready signed in Modal wrote [modal] into prove.toml next: poisson-prove sweep --dry-runWith --yes and no --max-cost, the table holds no cap. With a cap, where modal also writes
est_seconds_per_episode = 1.0, the seconds one rollout takes, because a cap is held against an
estimate and Modal’s estimate needs that time. It is the same default the cloud table gets, with
the same advice: set it from a run on this machine before you trust the estimate.
[modal]max_cost = 5.0est_seconds_per_episode = 1.0A 0.2 spec’s [burla] table
Section titled “A 0.2 spec’s [burla] table”In 0.2 a sweep on your own cluster read a [burla] table, and you started the cluster yourself.
That table is now [cloud], and Prove starts and stops the cluster. A sweep of a spec that still
holds [burla] is refused. Bare where says the answer is not ready, exit 0, with
next: poisson-prove where cloud.
where cloud moves the table in place. It keeps every key that carries over, in the order you had
them. It deletes head_url. It adds provider and region, which it asks for or takes from
--cloud and --region. Given this table:
[burla]head_url = "http://127.0.0.1:5001"nodes = 3machine_type = "m7i.xlarge"slots_per_node = 2usd_per_node_hour = 0.31price_asof = "read off the AWS console, 2026-10-30"ledger = "old-ledger.jsonl"stop_cost = 4.0max_cost = 6.0est_seconds_per_episode = 0.75the one command moves it:
poisson-prove where cloud --cloud aws --region us-east-2 --yesOutput4 lines
… signed in AWS 6030…4933 wrote [cloud] into prove.toml next: poisson-prove sweep --dry-runIts first line, left out above, says your AWS account, us-east-2, 3 × m7i.xlarge: the nodes and
the machine type came from the old table. The spec then holds:
[cloud]provider = "aws"region = "us-east-2"nodes = 3machine_type = "m7i.xlarge"slots_per_node = 2usd_per_node_hour = 0.31price_asof = "read off the AWS console, 2026-10-30"ledger = "old-ledger.jsonl"stop_cost = 4.0max_cost = 6.0est_seconds_per_episode = 0.75A ceiling the nodes do not fit
Section titled “A ceiling the nodes do not fit”--max-vcpus below what the nodes need is written as asked, and the answer says it is not ready.
There is no next: line, because no one command fixes it: raise the ceiling or ask for fewer
nodes.
poisson-prove where cloud --max-vcpus 8 --yesOutput2 lines
where your AWS account, us-east-2, 4 × m7i.2xlarge; not ready: 4 × m7i.2xlarge is 32 vCPUs, over max_vcpus 8 wrote [cloud] into prove.tomlA spec that holds both tables
Section titled “A spec that holds both tables”A spec that holds [cloud] and [modal] together does not say where it runs. A sweep of it with
no --backend is refused, exit 1, and so is bare where, in one line that names both tables.
poisson-prove where cloud, where modal or where local keeps one answer and takes the other
table out.
What an earlier sweep left running
Section titled “What an earlier sweep left running”A cloud sweep stops its nodes when it ends. If this machine stopped first (a crash, a kill -9,
a lost network), the nodes stop themselves, and Prove’s record of what it started stays open.
Bare where, on a spec that runs on your cloud account and a machine signed in to it, looks for
such a record. When it finds one it stops any node still listed, stops the cluster software on
this machine, closes the run’s ledger line if it is still open, and says so in one note: line
before its answer. It also reads the instances the cluster software tagged as its nodes that the
last sweep launched, from its start to its stop, and terminates any still running with the AWS
CLI, in one more note: line: a node whose launch was on its way when the sweep stopped is never
listed by the cluster software. The next cloud sweep does both.
When where cannot confirm that the nodes stopped, it says they may still be running, leaves the
record as it is, and exits 3. where cloud, where modal and where local do not look: they
change the spec only.
Exit codes
Section titled “Exit codes”0: the answer was printed, ready or not. Withlocal,modalorcloud, the table was written or taken out.1: refused, and nothing was written. The causes are: no spec in this folder; a spec that holds both tables, for barewhere; a cloud that is not offered; a region or machine type outside the price table; a number out of its range; a value that is missing with no terminal to ask on and no--yes; a table holding a key Prove does not know, which is never dropped; your cloud account chosen on Windows; another sweep running on the account from this machine.2: the command line is wrong.3: Prove could not confirm that what an earlier cloud sweep left has stopped; or an unexpected failure, whose traceback--debugprints.130: interrupted with Ctrl-C.
What it writes
Section titled “What it writes”Bare where writes nothing to the spec. With local, modal or cloud it writes the spec and
nothing else. It replaces the spec’s [modal] or [cloud] table, or a 0.2 [burla] table, with
the new one where the old one stood. It appends the table after a blank line when there was none.
For local it takes the table out. Every other byte of the file stays as it was, and the file is
replaced in one step, so a write that is cut short leaves the spec you had.
where never stores a cloud secret and never asks for one. Your cloud is reached only through
its own sign-in on this machine, and the checks are read-only: they write no cloud configuration,
sign in to nothing and create nothing in the account.
When bare where stops what an earlier cloud sweep left, it also closes that run’s line in the
spend ledger and updates Prove’s record under $XDG_STATE_HOME/poisson-prove/cloud/
(~/.local/state when the variable is unset).