Start here

Getting started

Install the CLI, log in with a registry key, install your first patch, run it, and roll it back.

View as Markdown

This walk-through installs a published patch on your own machine, runs it with and without the adapter, and rolls it back. It takes a few minutes plus the time to download the base model.

Before you start

  • Python 3.11 or newer.
  • For retoque run: torch, transformers and peft, which the runtime extra installs, and about 7 GB of free memory for Qwen2.5-1.5B in float32. CPU works but is slow. The base weights take about 3.1 GB of disk.
  • A Retoque account. Sign in with your email at /sign-in. Sign-in uses a one-time link, so there is no password.

1. Install the CLI

sh
pip install retoque                 # verify, install, enable, disable, rollback
pip install 'retoque[runtime]'      # adds torch, transformers, peft and safetensors for `retoque run`

The core package depends only on PyNaCl, for signature checks. Check the install with retoque --version.

2. Point the CLI at the registry

The CLI talks to http://localhost:3400 unless you tell it otherwise, which is only right for local development. Set the registry URL once in an environment variable or in ~/.config/retoque/config.json:

sh
export RETOQUE_API_URL=https://<registry host>

The CLI refuses plain http for anything except localhost, 127.0.0.1 and ::1. See Configuration for the config file.

3. Create a registry key and log in

In your workspace, open API keys and create a key. Keys start with rtq_ and carry scopes: registry:read to check the key, artifacts:download to request downloads, and installs:report for opt-in install check-ins. The key is shown once, because only a hash of it is stored.

sh
retoque login          # prompts for the key without echoing it

login checks the key against GET /api/v1/me, prints the account it belongs to, and stores it in ~/.config/retoque/credentials.json with mode 0600. The registry key is not a model API key. It is never sent to a model host or to a download link.

4. Find a patch and its base model

sh
retoque models list
retoque patches search ledger
retoque patches inspect <patch>@<version>

models list prints each supported base as org/name@<full commit>. patches inspect shows the manifest summary, digests and held-out numbers the registry reports for a version. Registry metadata on its own isn't proof of anything. The signature is checked when you verify or install.

5. Get a license

Open the patch page on Explore, read the terms for the version, and claim the license. A free license is a click-through: you accept the exact sha256 digest of the terms while signed in. Paid licenses come from an onchain purchase. See Licenses and entitlements.

6. Install

sh
retoque install <patch>@<version> \
  --model 'Qwen/Qwen2.5-1.5B-Instruct@989aa7980e4cf806f80c7fef2b1adb7bc71aa306'

Install runs a compatibility preflight, requests a single-use download link, checks the package sha256, extracts only the eight allowed files, verifies the signature and every file hash, and only then moves the files into ~/.retoque/patches/<patch>/<version>/ and writes ./retoque.lock. Any failure leaves nothing behind. The full sequence is in the CLI reference.

7. Run it, with and without the patch

Write the input as JSON:

json
{
  "user": "Today is 2026-03-02 (Monday).\nPay Halcyon Realty $4,200.00 for the office rent, due next Friday."
}
sh
retoque run --patch <patch> --input task.json
retoque run --patch <patch> --input task.json --no-patch

run loads the pinned base revision with trust_remote_code=False and safetensors only, decodes greedily, and prints which adapter sha256 was active, or that none was. The first run downloads the base model into your Hugging Face cache.

8. Turn it off or roll back

sh
retoque disable <patch>
retoque enable <patch>
retoque rollback <patch> --to <older version>
retoque status

Next