Run a job#

A job is a container image, its inputs and a list of outputs. You pay a budget into escrow when you submit it; workers are paid only for checked work, and the rest of the budget comes back to you. On the testnet everything is paid in test-TOG from the faucet.

Before you start#

tog-cli from the release, and a client.toml for the network (see client.toml).
An account key with test-TOG:

(umask 077; head -c 32 /dev/urandom > user.key)
tog-cli address user.key

A machine that storage workers can reach on one TCP port, if your job has inputs or you let the network store the image (below). tog-cli serves the files from there while storage workers take them.

What the first public testnet runs

CPU jobs only (x86-64), in isolation tier T1. Try every image on a local devnet first.

1. Package the image#

tog-cli pack-image takes an OCI image layout directory with exactly one manifest, for example from skopeo or docker buildx:

skopeo copy docker://docker.io/library/alpine:3.20 oci:layout:latest
# or: docker buildx build --output type=oci,tar=false,dest=layout .

tog-cli pack-image layout --out packed --platform linux/amd64

It writes packed/image.borsh (the image reference the job names) and packed/image.tar. Workers need the image's bytes. You can either:

let the network store it: pass --image-layout layout to submit-job, and the image goes into a storage deal that workers fetch from; or
host it yourself: upload image.tar and pass its address to pack-image with --locator https://… (also ipfs://… or ar://…).

2. Submit#

tog-cli submit-job \
  --image packed/image.borsh --image-layout layout \
  --run /bin/sh --run -c --run 'echo hello > /out/result' \
  --output result \
  --cpu-cores 1 --ram-bytes 268435456 --wall-time 60 \
  --budget 100 \
  --external /ip4/<YOUR_PUBLIC_IP>/tcp/30700 --listen /ip4/0.0.0.0/tcp/30700 \
  --key user.key -c client.toml
# prints the job id (64 hex digits)

The most used options:

Option	Default	What
`--run`		Entrypoint, then one `--run` per argument
`--env NAME=value`		Environment variable; repeatable
`--input NAME=PATH`		A file or directory, mounted at `/in/NAME`; repeatable
`--output PATH`	`result`	A path under `/out` to keep; repeatable
`--max-output-bytes`	1 MiB	Output size cap
`--cpu-cores`, `--ram-bytes`, `--scratch-bytes`	1, 256 MiB, 256 MiB	What the job may use
`--wall-time`	60	Time limit in seconds
`--budget`	100	Most the job may cost, in test-TOG
`--replicas`	3	How many workers check the result (3 to 7)
`--segments N`		Run in up to N segments with a checkpoint after each (see below)

Run tog-cli submit-job --help for the full list.

3. Follow it#

tog-cli job <JOB_ID> -c client.toml

A job moves through these states:

State	Means
`Unassigned`	Waiting for a worker
`Assigned`	A worker was chosen
`Running`	The worker is running it
`Verifying`	Other workers are checking the result
`Terminal`	Done, with an outcome: `Settled` (paid and refunded), `Refunded`, or a fault

A small job takes about ten minutes from submit to Settled on the testnet, most of it checking.

4. Get the output#

tog-cli get-output <JOB_ID> --out ./result-dir --key user.key -c client.toml
cat result-dir/result

get-output fetches the output from the storage workers that hold it, pays them from your account, checks the bytes against what the job committed to, and unpacks them. --out must not exist yet. If you already have the stored archive, tog-cli open-output <JOB_ID> --archive FILE --out DIR opens it without fetching.

Long jobs#

A job that runs for a long time can run in segments. The program reads the segment number from TOG_SEGMENT and keeps its state under /out; after each segment the worker saves a checkpoint. If a worker goes away, another one resumes from the last checkpoint instead of starting over.

tog-cli submit-job … --segments 10 --segment-wall-time 600 --checkpoint-max-bytes 104857600