Skip to main content
synth-ai serve launches a task app locally with uvicorn.
  • Skipping APP_ID opens an interactive picker sourced from registered apps, demos, and nearby modules.
  • Credentials come from .env files supplied via --env-file, declared on the app entry, or discovered automatically. If none exist the command offers to create one and guides you through the required keys.
  • When an environment key is missing it prompts for ENVIRONMENT_API_KEY (and optional vendor keys), writes them back to .env, and loads the values into the process.
  • Tracing (SFT JSONL, local Turso DB) is configurable at runtime—the CLI prompts for directories and paths when you omit the flags.
  • Ports and reload options are managed for you. --force kills conflicting processes; --reload enables uvicorn’s autoreload loop.
  • The environment is enriched before startup: keys are minted when supported, tracing variables are set, and demo directories created by synth-ai setup are detected automatically.

​
Options

  • APP_ID — Task app identifier. Omit to open the interactive picker; provide one to bypass the prompt.
  • --host VALUE — Listen address (0.0.0.0 by default). Override when you only want to bind to localhost.
  • --port VALUE — Port to bind. If omitted the CLI prompts you. Combine with --force when you want the helper to terminate conflicting processes automatically.
  • --env-file PATH — One or more .env files to load before startup. Repeat the flag to merge multiple files.
  • --reload / --no-reload — Toggle uvicorn autoreload. Enable it while developing; leave it off in production for stability.
  • --force / --no-force — Whether to kill processes already bound to the selected port. Set --force when you want the CLI to free the port automatically.
  • --trace DIR — Directory for traced rollout JSONL files. If omitted the CLI asks whether to enable tracing at all.
  • --trace-db PATH — Override the default SQLite/Turso database path used for tracing metadata.
uvx synth-ai serve grpo-crafter --port 8001 --env-file .env.crafter
Example session (defaults prompted): 
synth@Nomans-Resolve sdk % uvx synth-ai serve grpo-crafter
Port to serve on [8001]: 8001

Tracing captures rollout data (actions, rewards, model outputs) to a local SQLite DB.
This data can be exported to JSONL for supervised fine-tuning (SFT).
Enable tracing? [Y/n]: y
Trace directory [~/qa/sdk/traces/v3]:
Trace DB path [~/qa/sdk/traces/v3/synth_ai.db]:
Using env file(s): /Users/synth/qa/sdk/.env
Tracing enabled. SFT JSONL will be written to /Users/synth/qa/sdk/traces/v3
Tracing DB path set to /Users/synth/qa/sdk/traces/v3/synth_ai.db
ENVIRONMENT_API_KEY not set. Run `uvx synth-ai setup`, or enter it now.
ENVIRONMENT_API_KEY: sk-...
Groq API key (optional):
INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

​
Notes

  • When tracing is enabled the CLI sets TASKAPP_TRACING_ENABLED, TASKAPP_SFT_OUTPUT_DIR, and the local Turso connection string so exporters and evaluators see consistent paths.
  • Inside the demo workspace the command prints a follow-up hint pointing to rollout scripts, so new users know how to collect traces immediately after starting the service.