Train Your Model on Your Local Machine

Synth’s CLI ships a single entry point—uvx synth-ai deploy—that can host any task app directly on your laptop. The local runtime keeps everything on your machine by spawning uvicorn in-process, wiring in your .env secrets, and validating that the FastAPI task app exposes the required endpoints (/, /health, /info, /task_info, /rollout) before anything starts listening.

When to use the local runtime

• Fast feedback while iterating on routes, prompts, or trace instrumentation.
• Running baselines or smoke tests without exposing endpoints to the public internet.
• Validating that /rollout responses are well-formed before promoting to Modal or a tunnel.

Prerequisites

1. uv (or Python 3.11+) to run uvx synth-ai ….

2. Synth CLI pairing so the SDK can populate SYNTH_API_KEY and ENVIRONMENT_API_KEY:

   uvx synth-ai setup
   

   The setup command opens the dashboard, performs the handshake, and writes both keys to your repo’s .env.

3. A validated task app module. The CLI checks and rejects apps that do not compile, lack an ASGI app, or miss mandatory endpoints, so fix any errors before retrying.

Start a local task app

uvx synth-ai deploy \
  --runtime local \
  --env examples/warming_up_to_rl/.env \
  --port 8765 \
  examples/warming_up_to_rl/task_app/grpo_crafter.py

What happens under the hood:

1. .env files are loaded (and override process env vars) so both API keys are present.
2. validate_task_app imports your Python module and ensures all required FastAPI routes exist.
3. LocalDeployCfg sets ENVIRONMENT_API_KEY plus TASKAPP_TRACING_ENABLED=1 (unless --no-trace), then uvicorn serves the ASGI app on the requested host/port.
4. The CLI prints Serving task app at http://HOST:PORT; stop the server with Ctrl+C.

Handy flags

Flag	Description
--env PATH (repeatable)	Additional .env files to load.
--host / --port	Change the bind address (default 127.0.0.1:8000).
--trace/--no-trace	Toggle trace capture. When disabled, TASKAPP_TRACING_ENABLED is cleared.
--force	Kill any process already bound to the port (legacy serve flag, still honored).
--reload	Enable uvicorn autoreload for hot code swaps (defaults to off).

Tip: The CLI automatically discovers task apps listed in synth_ai/task_apps.py. If you omit the path, it will prompt you to pick one interactively.

Verifying the deployment

1. Hit GET /health in another terminal: curl -H "X-API-Key: $ENVIRONMENT_API_KEY" http://127.0.0.1:8765/health.

2. Run a smoke test to mimic trainer rollouts:

   uvx synth-ai smoke --url http://127.0.0.1:8765 --env-name crafter
   

3. Inspect traces under the directory you passed via --trace (or set TASKAPP_TRACING_ENABLED=0 to disable when benchmarking).

Next steps

• Keep iterating locally until /rollout responses, traces, and smoke tests look good.
• When you’re ready to share the app with Synth cloud trainers, either open a Cloudflare tunnel or follow the Modal deployment guide for a fully managed container.