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-agentand run everyyasp-toolkitcommand. 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-agentinstall. 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
yaspshell only) the Claude Code CLI on yourPATH. - 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?
- Compile your first model — start a runner on the target machine, then prepare, compile, and verify.
- Generate your first kernel — start an eval runner, then export, generate, and inspect an optimized GPU kernel.