Skip to content

Installation

yasp-agent ships two commands — yasp (the agent shell) and yasp-toolkit. Install it into a project venv as shown below. To expose the commands on your PATH everywhere instead, advanced users can install globally with pipx.

Two machines

A yasp workflow spans two machines, and it matters which one you're on:

  • Reference machine — your development box, where you install yasp-agent and run every yasp-toolkit command. It's the reference because the PyTorch model you author here is what the results are checked against.
  • Target machine — the GPU box the work runs on. It needs only Docker, the NVIDIA Container Toolkit, and SSH access from the reference machine — no yasp-agent install. A containerized worker does the work there.

You drive everything from the reference machine; the one time you touch the target directly is to start the worker — over SSH, still from the reference machine.

The two can also be the same machine — a dGPU workstation where you develop and run the worker; just run the "over SSH" commands locally and skip the SSH setup.

Everything below sets up the reference machine.

Prerequisites

  • Python 3.11 or newer
  • A yasp API key — see Get your API Token.
  • (for the yasp shell only) the Claude Code CLI on your PATH.
  • SSH access to the target machine, with Docker and the NVIDIA Container Toolkit installed there.

Get a registry key

Export your API key first. The exchange below uses it, and so does every yasp-toolkit command once the package is installed:

export YASP_API_KEY='yasp_...'

Packages come from the private yasp registry. Exchange your API key for a long-lived (about 6 months) registry key:

export REGISTRY_KEY=$(curl -fsS -X POST \
  -H "Authorization: Bearer $YASP_API_KEY" -G \
  --data-urlencode "audience=nexus-api" \
  --data-urlencode "scope=nexus-read" \
  "https://compile.yasp.ai/api/token")

It is needed once, for yasp-agent itself; yasp-toolkit install mints its own for everything after.

Exchange failing, or no registry access?

If the request errors or you can't reach the registry, contact support@yasp.ai with the command output.

Install

Install yasp-agent into a project virtualenv. The commands are available whenever the venv is activated.

Create and activate the venv:

python3 -m venv .venv
source .venv/bin/activate

Install yasp-agent

The base install holds the account, registry and transfer commands, and no PyTorch:

pip install \
  --extra-index-url "https://token:${REGISTRY_KEY}@nexus.yasp.ai/repository/pypi-hosted/simple/" \
  yasp-agent

Note

The installation also exposes ytk as a short alias for yasp-toolkit.

Want the commands on your PATH everywhere, or use uv?

Advanced users can install globally with pipx instead of a per-project venv — see Install globally with pipx. For uv, as a tool or in a project venv, see Install with uv.

Log in

yasp-toolkit login

Add the products

yasp-toolkit install mints the registry key from your login and installs into the active venv:

Extra Commands
gaia eval, kernelgen
kronos-edge embedded, dataset

Both pull in PyTorch, as the cpu build unless you name another with --torch. Pick one:

yasp-toolkit install gaia kronos-edge
yasp-toolkit install gaia kronos-edge --torch cu128

Swap cu128 for the build matching your driver (cu126, cu128, cu130, …).

yasp-toolkit install gaia kronos-edge --torch rocm6.4

Swap rocm6.4 for the ROCm build matching your install.

The CUDA build on Linux, CPU on macOS and Windows:

yasp-toolkit install gaia kronos-edge --torch default

The build is remembered for later installs; the PyTorch getting-started page lists every build. To pin the PyTorch version too, add it as a package:

yasp-toolkit install gaia kronos-edge --torch cu128 -p 'torch==2.9.1'

Options: yasp-toolkit install.

Verify the installation:

yasp --help
yasp-toolkit --help

[Optional] Persist your API key

Every yasp-toolkit command reads your API key from the YASP_API_KEY environment variable. Rather than exporting it in each new shell, add it to your shell profile so it's always set:

echo "export YASP_API_KEY='yasp_...'" >> ~/.bashrc   # or ~/.zshrc

Security tip

We recommend using the operating-system keyring instead of an environment variable — see Store your API key in the keyring.

[Optional] Widen table output

yasp-toolkit prints wide Rich tables (worker lists, verification metrics) that wrap and collapse at the default 80 columns. Set a wider width once so they stay on one line:

export COLUMNS=200    # or prepend per command: COLUMNS=200 yasp-toolkit …

[Optional] Update & uninstall

Make sure your venv is active first when updating or uninstalling.

source .venv/bin/activate

Update

Upgrades yasp-agent, every installed yasp package and their dependencies:

yasp-toolkit install -U

Uninstall

pip uninstall yasp-agent

Where to next?