Getting started

This guide builds Toki from source, starts a coordinator, connects one worker and runs a first remote command. Everything runs on one machine here, but the worker could just as well be on another one.

Prerequisites

• Rust through rustup. The repository pins its toolchain in rust-toolchain.toml, so rustup installs the right release when you build.
• Git, used by workers to fetch the exact commit they build.
• Native build tools for your platform:
  • Windows: an MSVC developer environment with the Windows SDK.
  • macOS: Xcode or the Command Line Tools.
  • Linux: GCC/G++, binutils and the glibc development files. Ubuntu 24.04 LTS x86_64 is the reference target.

Build from source

From a checkout of the Toki repository:

cargo build -p toki --release --locked

This produces three executables in target/release/:

Executable	Purpose
toki	CLI, coordinator, client and daemon commands
toki-worker	standalone network worker
toki-benchmark	the standing benchmark harness

To build only the worker:

cargo build -p toki --bin toki-worker --release --locked

Prebuilt binaries

Releases also ship stripped binaries for Windows x64, Linux x64 and macOS Apple Silicon: toki-<platform> and toki-worker-<platform>, plus a toki-release.json manifest with each file's SHA-256 and size. The macOS binaries are not Apple-notarised. On Unix, make a download executable with chmod +x.

Check the build:

toki --version
toki roles

Try a local run

toki local run executes a program through the combined local daemon, without a coordinator, and exits with the program's exit code:

toki local run -- cargo --version

This is a good smoke test, but it does not leave your machine. The rest of this guide sets up real remote execution.

1. Create a coordinator

Initialise a new, private directory once. The directory must not exist yet:

toki build init --dir ~/toki-coordinator --server-name localhost --listen 127.0.0.1:7444

It prints the paths of the two files it wrote:

{"serverConfig":".../toki-coordinator/server.json","clientConfig":".../toki-coordinator/client.json"}

The directory holds the server key, a CA certificate, the SQLite database, server.json and a client credential in client.json. Keep its permissions private.

Never re-run init on a live coordinator

build init creates a new identity. To change addresses later, use toki build configure instead (see Workers).

Start the coordinator in its own terminal:

toki build serve --config ~/toki-coordinator/server.json

2. Issue a worker credential

Credentials are issued only through the coordinator's protected local administration endpoint. On Linux and macOS this is admin.sock in the coordinator directory:

toki daemon issue --socket ~/toki-coordinator/admin.sock --role worker --subject desktop

On Windows the endpoint is a named pipe; use the socket value from server.json.

The command prints the new token once. Copy it now; only a digest is stored.

3. Configure and start the worker

Create toki-worker.json. Copy coordinatorUrl, serverName and caPem from the coordinator's client.json, and use the worker token from step 2:

{
  "coordinatorUrl": "https://localhost:7444",
  "serverName": "localhost",
  "caPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "token": "WORKER_TOKEN_FROM_STEP_2",
  "workDir": "./workspace",
  "stateDir": "./worker-state",
  "builds": {
    "targetDir": "/absolute/path/to/toki-targets",
    "jobs": 8,
    "labels": ["build-host"],
    "repositories": ["https://github.com/your-org/your-repo.git"]
  }
}

• workDir and stateDir may be relative; they resolve against the config file.
• builds.targetDir must be absolute. It holds the worker's Cargo target slots.
• builds.repositories is the HTTPS allowlist. Clients cannot supply local paths or mirrors.
• labels lets clients select this worker as class:build-host.

Start the worker:

toki-worker --config toki-worker.json

The worker connects outward; it opens no listening port. Keep this file private, since it contains a credential.

4. Run your first remote build

Check the worker is connected:

toki client workers --config ~/toki-coordinator/client.json

Write a request file, build.json. The commit must be the complete 40- or 64-character object name of a commit reachable in an allowlisted repository:

{
  "key": "first-build-1",
  "worker": "class:build-host",
  "timeoutSeconds": 1800,
  "command": {
    "program": "cargo",
    "args": ["test"],
    "source": {
      "repository": "https://github.com/your-org/your-repo.git",
      "commit": "0123456789abcdef0123456789abcdef01234567"
    }
  }
}

Submit it and follow it:

toki client submit --config ~/toki-coordinator/client.json --request build.json
toki client get --config ~/toki-coordinator/client.json --id req-<identity>

Each command prints one line of compact JSON. The id in the submit summary is what you pass to get and cancel. A completed build carries its exitCode and a receiptId. Add --view full to get to see the output bytes and every attempt.

Uncommitted work

A Git source builds committed source only. Commit and push your changes so the worker can fetch the commit, or publish them as a Gin snapshot.

Where to go next

• Concepts: what keys, leases and receipts mean.
• Workers: reloads, containment limits and managed workers.
• Client: every toki client operation and the TypeScript client.
• Builds: artefacts, toolchains, Gin sources and sparse views.