Tinker SDK Skill#

Tinker is an ML platform SDK by Thinking Machines AI for managing training runs, model checkpoints, and fine-tuning workflows. This skill covers the CLI, Python SDK, and the tinker-cookbook training recipes.

Source repos:

• SDK: https://github.com/thinking-machines-lab/tinker
• Cookbook: https://github.com/thinking-machines-lab/tinker-cookbook
• This skill: https://github.com/zjrwtx/max_skills

IMPORTANT — Always use the latest version: Before running any Tinker command or cookbook recipe, ensure the latest version is installed:

bash

uv pip install --upgrade tinker
# For cookbook, pull latest and reinstall:
cd <cookbook-dir> && git pull && uv pip install -e .

When you need more detailed information about API internals, recipe implementations, or SDK source code, always check the latest code from these repos — do NOT rely on cached or outdated knowledge. Clone or browse the repos directly to get up-to-date APIs and options.

Quick Start#

Authentication#

bash

# Option 1: Environment variable (preferred)
export TINKER_API_KEY="your-api-key"

# Option 2: Config file (~/.tinker/config.json)
mkdir -p ~/.tinker
echo '{"api_key": "your-api-key"}' > ~/.tinker/config.json

Verify Installation#

bash

tinker version
tinker run list --limit 3

Tinker Path Format#

All checkpoint operations use tinker paths:

text

tinker://<RUN_ID>/<TYPE>/<STEP>

• TYPE: weights (training) or sampler_weights (sampler)
• Example: tinker://run-abc123/weights/00040

---

CLI Commands#

Global Options#

• --format [table|json] or -f — output format (default: table)
• -h / --help — help on any command

Run Commands#

bash

# List training runs (default: 20, use --limit=0 for all)
tinker run list [--limit N] [-c COLUMNS]

# Available columns:
#   id, model, owner, lora, updated, status,
#   checkpoint, checkpoint_time
# Default columns: id, model, lora, updated, status

# Show detailed info for a specific run
tinker run info <RUN_ID>

Checkpoint Commands#

bash

# List checkpoints (all runs, or filter by --run-id)
tinker checkpoint list [--run-id ID] [--limit N]

# Show checkpoint details
tinker checkpoint info <TINKER_PATH>

# Download and extract checkpoint locally
tinker checkpoint download <TINKER_PATH> \
  [-o OUTPUT_DIR] [--force]

# Toggle public access
tinker checkpoint publish <TINKER_PATH>
tinker checkpoint unpublish <TINKER_PATH>

# Set or remove expiration (TTL in seconds)
tinker checkpoint set-ttl <TINKER_PATH> --ttl 604800
tinker checkpoint set-ttl <TINKER_PATH> --remove

# Delete checkpoints (by path or by filters)
tinker checkpoint delete <PATH1> [PATH2 ...] [-y]
tinker checkpoint delete --run-id <ID> \
  [--type weights|sampler_weights] \
  [--before DATE] [--after DATE] [-y]

# Push checkpoint to HuggingFace Hub
tinker checkpoint push-hf <TINKER_PATH> \
  [-r REPO_ID] [--public] [--revision REV] \
  [--commit-message MSG] [--create-pr] \
  [--allow-pattern PAT] [--ignore-pattern PAT] \
  [--no-model-card]

For full flag details and output format examples, read references/cli-reference.md.

---

Common Workflows#

1. Find and Download a Checkpoint#

bash

# Step 1: Find your training run
tinker run list

# Step 2: Inspect the run
tinker run info <RUN_ID>

# Step 3: List available checkpoints
tinker checkpoint list --run-id <RUN_ID>

# Step 4: Download
tinker checkpoint download \
  tinker://<RUN_ID>/weights/<STEP> \
  -o ./models/ --force

2. Push a Checkpoint to HuggingFace#

bash

# Prerequisite: authenticate with HF
# pip install huggingface_hub && hf auth login

# Push as public PEFT adapter
tinker checkpoint push-hf \
  tinker://<RUN_ID>/sampler_weights/<STEP> \
  -r myorg/my-lora --public

# Or create a PR instead of direct push
tinker checkpoint push-hf \
  tinker://<RUN_ID>/sampler_weights/<STEP> \
  -r myorg/my-lora --create-pr

3. Clean Up Old Checkpoints#

bash

# Delete checkpoints older than a date
tinker checkpoint delete --run-id <RUN_ID> \
  --type weights --before 2025-01-01 -y

# Delete specific checkpoints
tinker checkpoint delete \
  tinker://<RUN_ID>/weights/0001 \
  tinker://<RUN_ID>/weights/0002 -y

4. Scripting with JSON Output#

bash

# Export all runs as JSON
tinker --format json run list --limit=0 > runs.json

# Parse with jq
jq '.runs[].training_run_id' runs.json

# Batch list checkpoints per run
for rid in $(jq -r '.runs[].training_run_id' runs.json)
do
  tinker --format json checkpoint list --run-id "$rid"
done

---

Cookbook Recipes#

The tinker-cookbook provides ready-to-use training recipes. Repo: https://github.com/thinking-machines-lab/tinker-cookbook

Recipe Architecture#

Every recipe follows the same pattern:

python

import chz
from tinker_cookbook.rl import train  # or supervised

# 1. Build a typed config via chz.Blueprint
def build_config_blueprint() -> chz.Blueprint[train.Config]:
    return chz.Blueprint(train.Config).apply({
        "model_name": "meta-llama/Llama-3.1-8B",
        "learning_rate": 2e-4,
        ...
    })

# 2. Run the training loop
def main(config):
    asyncio.run(train.main(config))

# 3. CLI entry point with chz overrides
if __name__ == "__main__":
    bp = build_config_blueprint()
    bp.make_from_argv(sys.argv[1:])
    main(bp.make())

Override any config field from the command line:

bash

python -m tinker_cookbook.recipes.sl_basic \
  --model_name "Qwen/Qwen3-8B" \
  --learning_rate 1e-4 \
  --log_path /tmp/my-run

Running SFT (Supervised Fine-Tuning)#

bash

# Minimal SFT on NoRobots dataset
python -m tinker_cookbook.recipes.sl_basic

# With custom dataset (JSONL of conversations)
# Edit sl_basic.py to use FromConversationFileBuilder:
#   file_path="/path/to/conversations.jsonl"
# Format: same as example_data/conversations.jsonl

Running RL Training#

bash

# Math RL on GSM8K
python -m tinker_cookbook.recipes.rl_basic

# Override hyperparameters
python -m tinker_cookbook.recipes.rl_basic \
  --learning_rate 4e-5 \
  --max_tokens 256

Available Recipes#

RecipeTypeUse Casesl_basicSFTMinimal SFT templaterl_basicRLMinimal RL templatechat_sl/SFTConversations (Tulu3)math_rl/RLMath reasoning (GSM8K)code_rl/RLCode (sandboxed exec)preference/RLHFSFT → reward → RLsearch_tool/RLRetrieval tool usedistillation/SFT/RLTeacher→studentprompt_distillation/SFTInternalize promptsmultiplayer_rl/RLSelf-play / multi-agentrubric/RLLLM grader rubricsverifiers_rl/RLCommunity envsvlm_classifier/SFTVision-languageharbor_rl/RLTerminal/SWE tasks

Key Utilities#

python

from tinker_cookbook import model_info

# Get the right renderer for a model
renderer = model_info.get_recommended_renderer_name(
    "meta-llama/Llama-3.1-8B"
)

# Checkpoint save/resume
from tinker_cookbook import checkpoint_utils
resume = checkpoint_utils.get_last_checkpoint(log_path)

Supported Models#

Llama 3.x, Qwen 3/3.5, DeepSeek V3, Nemotron 3, Kimi K2/K2.5, GPT-OSS, and 30+ more. Each model has a recommended renderer in model_info.py.

For recipe deep-dives, renderer details, dataset builder patterns, and RL environment setup, read references/cookbook-recipes.md.

---

Quick Troubleshooting#

ProblemFixAuth failureCheck TINKER_API_KEY or ~/.tinker/config.jsonCheckpoint not foundVerify path format tinker://RUN/TYPE/STEP; list available with tinker checkpoint list --run-id IDDownload failsUse --force to overwrite; check disk spaceCookbook import erroruv pip install -e . in cookbook dir; needs Python 3.10+chz override syntax--field value (flat) or --outer.inner value (nested)Rate limitWait and retry; reduce --limit for batch opsHF push failsRun hf auth login; install huggingface_hub

For the full error catalog, read references/troubleshooting.md.

---

Detailed References#

When the SKILL.md cheat sheet is not enough:

• references/cli-reference.md — Every flag, output format example (table + JSON), exit codes, date format rules, bulk delete filter logic
• references/cookbook-recipes.md — Per-recipe config fields, renderer selection, dataset builder interface, RL environment pattern, hyperparameter guidance
• references/troubleshooting.md — Extended error catalog with 15+ error-to-fix mappings, network/proxy issues, W&B integration, checkpoint corruption