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 3.12
  • 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

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")

Once yasp-agent is installed

You no longer need the curl — mint the key with yasp-toolkit registry key, which reads your API key from YASP_API_KEY and prints a fresh key:

export REGISTRY_KEY=$(yasp-toolkit registry key)

This is the command the worker-deploy guides point back to.

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 PyTorch first

yasp-agent depends on PyTorch.

These cover the common cases; the PyTorch getting-started page lists every variant and the exact --index-url for each. Pick one:

pip install --index-url https://download.pytorch.org/whl/cpu torch==2.9.1

pip install --index-url https://download.pytorch.org/whl/cu128 torch==2.9.1

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

pip install --index-url https://download.pytorch.org/whl/rocm6.4 torch==2.9.1

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

Lets pip choose — the CUDA build on Linux, CPU on macOS/Windows.

Linux hosts will default to NVIDIA dependencies.

pip install torch==2.9.1

Install yasp-agent

torch is already satisfied from the step above, so this won't pull a second build:

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

Note

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

Want the commands on your PATH everywhere?

Advanced users can install globally with pipx instead of a per-project venv — see Install globally with pipx.

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

Prefer your OS keyring?

Advanced users can store the key in 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

With the venv activated:

# update (re-mint the registry key first if yours expired)
export REGISTRY_KEY=$(yasp-toolkit registry key)
pip install --upgrade \
  --extra-index-url "https://token:${REGISTRY_KEY}@nexus.yasp.ai/repository/pypi-hosted/simple/" \
  'yasp-agent[gaia,kronos]'    # pin with 'yasp-agent[gaia,kronos]==X.Y.Z'

# uninstall
pip uninstall yasp-agent

Where to next?