Skip to main content
Synth handles the orchestration required to fine-tune models (SFT) and run online reinforcement learning (RL) on agent-style workloads. Follow this guide to pair the CLI with your Synth workspace, stand up a task app, and launch your first job.

​
Prerequisites

  • Python 3.11 or newer
  • uv (or pipx) so you can run uvx
  • Synth account (https://usesynth.ai) with organization access
  • Modal account (https://modal.com) if you will deploy task apps remotely
  • Git checkout of your task app or one of the bundled demos

​
1. Install the CLI

# Install uv if you do not already have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Confirm the Synth CLI is reachable
uvx synth-ai --help
uvx synth-ai always executes the latest published CLI without touching your global environment. To pin a specific version use uv tool install synth-ai or pip install synth-ai.

​
2. Pair the CLI with the dashboard

  1. Navigate to your project directory.
  2. Run uvx synth-ai setup.
  3. Complete the browser pairing flow (it reuses your dashboard session).
The command writes a .env file alongside your project containing:
  • SYNTH_API_KEY – authorizes CLI and SDK calls to Synth.
  • ENVIRONMENT_API_KEY – authenticates requests to your task apps.
Keep this .env in your repo root so downstream commands discover it automatically. Note: the CLI caches this path and auto-loads the .env for every command. Use --env-file only when you want to override the defaults.

​
3. Validate access from your shell

curl -H "Authorization: Bearer $SYNTH_API_KEY" \
  https://api.usesynth.ai/api/learning/jobs?limit=1
You should receive a JSON response (an empty list is fine for new accounts). If the call returns 401 re-run uvx synth-ai setup to refresh your .env.

​
4. Bootstrap the math demo

The SDK ships a ready-to-run math environment that exercises the full Synth pipeline: 
# Materialise demo files into ./math_demo (or choose another directory)
uvx synth-ai demo init

# If you skipped step 2, pair the demo now (writes math_demo/.env)
uvx synth-ai demo setup
The CLI remembers this directory and .env path, so subsequent demo commands run from the same workspace automatically.

​
5. Run the task app locally

Launch the math task app on http://127.0.0.1:8080: 
uvx synth-ai demo deploy --local
The server streams traces to traces/v3/ inside the demo directory. When you are ready for a remote deployment, re-run uvx synth-ai demo deploy --name synth-math-demo to package the same app for Modal.

​
6. Collect your first rollouts

Open a second terminal in the demo directory and run: 
uvx synth-ai eval \
  --task-url http://127.0.0.1:8080 \
  --model Qwen/Qwen3-0.6B \
  --seeds 0-3 \
  --trace-db traces/v3/synth_ai.db
This records rollouts in traces/v3/synth_ai.db, ready for either SFT filtering or RL training. Want to see the full RL loop? Kick off the curated math run: 
uvx synth-ai demo run --batch-size 4 --group-size 16 --model Qwen/Qwen3-0.6B
The command validates your task app, submits the job, and streams trainer events until the run completes.

​
7. Choose your workflow

Keep the CLI paired and your task app healthy; every other Synth workflow builds on these steps.