What is Toki?

Toki is a distributed build, test and validation engine written in Rust. Its first job is to take heavy Rust builds and test runs off the machines where agents and developers work, run them on other machines, and record exactly what happened.

Toki is a build and test system. It owns the history of the tests it runs, and it is designed to take in test results from CI as well.

Whole-command remote execution

Toki does not split a build into thousands of small compiler steps. It runs one whole command on one worker: for example cargo test against an exact commit. Cargo still owns compilation, build scripts, linking and its own freshness decisions inside that command.

A network build goes like this:

1. A client submits a request: an idempotency key, a worker selector, a timeout and a command with its source (an exact Git commit or a published Gin snapshot).
2. The coordinator stores the request durably and picks a connected worker that matches the selector and, when given, the required OS and architecture.
3. The worker fetches the exact source, checks it out into a disposable directory, runs the command under native process containment and reports output, exit code and resource accounting.
4. The coordinator publishes a receipt for the completed attempt.

The command families a network worker accepts today are deliberately narrow:

Program	Accepted forms
cargo	build, check, test, clippy, bench (and cargo -vV)
rustc	any arguments except -o and --out-dir
node	node --test (and node --version)

Retrying a submission with the same key and body returns the original build. Changing the body under the same key is refused. See Builds for the details.

Record-only by default

Whole-command results are recorded, not reused. Toki does not claim that a plain build is hermetic, so it never serves one build's result in place of another run. See action keys.

Receipts as evidence

When an attempt completes, Toki publishes a receipt together with its own versioned execution payload (toki.execution). The payload records:

• the provider-qualified source identity the action ran against;
• the platform the result holds for (OS, architecture and toolchain digest);
• the declared inputs and the hermeticity class decided at admission, with secrets redacted;
• every attempt of the action and its outcome;
• test evidence checked against what was selected to run;
• retained logs, artefacts and the native containment report.

Receipts leave Toki through a durable outbox. A consumer reads pending entries, hands them on and acknowledges them. If it crashes in between, the same entry is delivered again with the same bytes, so the receiver can deduplicate on the receipt id. See Receipts.

Toki, Gin and Tama

Toki is part of the Tama toolchain, alongside Gin.

• Gin is source control and metadata. It owns the evidence envelope, its attestation and its trust classification. Toki owns only the payload inside, and its trust tier is always observational. Toki can build published Gin snapshots directly, without a Git export.
• Toki is the build and test system. It owns execution, receipts and test history, and it is designed to ingest CI output.
• Tama can download, configure and supervise Toki's coordinator and workers. Toki's own coordinator, worker commands and configuration also work without Tama.

Source identities from Git and Gin are kept apart. A Git identity is never claimed to equal a Gin hash. See source providers.

Supported platforms

Toki runs natively on each platform; there is no emulation layer. Status today:

Platform	Status
Windows x86_64 (MSVC)	Native worker and coordinator. Release binaries. CI builds and tests natively. Job Object containment with CPU and memory limits.
macOS Apple Silicon (aarch64)	Native worker and coordinator. Release binaries (not Apple-notarised). CI builds and tests natively. Best-effort descendant tracking; CPU and memory limits are refused. Heavy builds are not shared with other work: run them only while the Mac is otherwise drained (Toki does not enforce this itself).
Linux x86_64, Ubuntu 24.04 LTS, glibc	The Linux reference target. Release binaries. CI builds and tests natively. cgroup v2 containment with a delegated subtree. Reference qualification is not yet complete.
Windows aarch64, macOS x86_64	Toolchain manifests exist; no release binaries are published.
Other Linux distributions, musl, Linux on ARM	Not supported. Toolchain provisioning refuses them.

Containment is not a sandbox

Toki's process containment tracks and limits resources for trusted, cooperative workloads. It is not a security sandbox. Use only coordinators and workers you trust. Requests that ask for secrets or trusted publication are refused on every platform.

Status of the project

Toki is under active development. Some parts described in this site are designed but not built yet, and they are marked as planned where they appear. Performance targets are treated as hypotheses until controlled benchmarks support them.

Next steps

• Getting started: build Toki and run your first remote command.
• Concepts: the vocabulary used across the docs.
• Workers: run a worker on your own machine.