synthtraffic Get started
Docs menu

Getting started

Install Quickstart Overview Synthtraffic MCP

Build a scenario

Scenario file Generators vars and const Time and pace Defaults Relationships Schedules Instances Lifecycle Collections Connections Delivery behavior

Connectors

Kafka PostgreSQL HTTP File S3 GCS Azure Blob

Expressions

Syntax IDs and sequences Random Faker Selection Modifiers Math Logic Collections ref and previous Time functions Strings and env Easing

CLI

sample run studio

Studio

Overview Workspace and editor Sample and timeline Run and Stop

Reference

Diagnostics Faker data

Getting started

Install

Goal: get synthtraffic running on your machine, then connect an issued license.env.

You can run Synthtraffic either by downloading the CLI or by pulling a Docker image.

Download the latest release from SynthTraffic/synthtraffic-releases.

  1. Open the newest release on that page.
  2. Download the archive for your OS and CPU, then extract the binary: synthtraffic on Linux and macOS, or synthtraffic.exe on Windows.
  3. Add the folder that contains the binary to your PATH (not the binary file itself).
  4. Confirm it runs:

For example, if the Windows binary is C:\Tools\synthtraffic\synthtraffic.exe, add C:\Tools\synthtraffic to PATH. Open a new terminal afterwards.

On macOS or Linux, if the binary is /usr/local/bin/synthtraffic, add /usr/local/bin to PATH. 

synthtraffic help

Continue below to set a license with SYNTHTRAFFIC_LICENSE_FILE.

Common install problems

What you see What to check
synthtraffic is not recognized Confirm the folder containing the extracted binary is on PATH, then reopen the terminal.
Permission denied on macOS or Linux Make the extracted binary executable (chmod +x synthtraffic).

License

Choose a Free Trial or Developer license on Pricing to begin checkout. Contact is for Enterprise pricing and custom terms. If you already have an issued license.env, continue below. The file stays on your machine.

Set the license

The CLI points to the file with one environment variable. Docker receives the file on every run.

Set SYNTHTRAFFIC_LICENSE_FILE to your license.env. Use the command for your shell:

macOS/Linux shell:

export SYNTHTRAFFIC_LICENSE_FILE=/Users/you/Downloads/license.env

PowerShell:

$env:SYNTHTRAFFIC_LICENSE_FILE = "C:/Users/you/Downloads/license.env"

These commands set the variable for the current terminal session. Changing the env var (or the file it points at) changes the active license. You will confirm it works when you run sample in Quickstart — a missing or expired file prints an error before any events.

Which commands need it?

  • The three product commands—sample, run, and studio—require a valid license.
  • Viewing command help with synthtraffic --help does not require a license.

How Synthtraffic finds the file

  • CLI: SYNTHTRAFFIC_LICENSE_FILE — path to a license.env
  • Docker: --env-file ./license.env on every docker run

Common license problems

What you see What to check
license not found CLI: export SYNTHTRAFFIC_LICENSE_FILE to a license.env path. Docker: pass --env-file ./license.env.
The signature is rejected Copy every issued field exactly.
license expired Get a new license through Pricing (or Contact for Enterprise), then point SYNTHTRAFFIC_LICENSE_FILE at the new file. With Docker, pass the new file using --env-file.
Docker works once but not on the next run Pass --env-file every time.

What is in the License file?

An issued file contains your license details and a signature:

LICENSE_ID=...
LICENSE_EMAIL=you@example.com
LICENSE_ORGANIZATION=Your Org
LICENSE_EDITION=Synthtraffic Free Trial
LICENSE_EXPIRATION=2026-09-21
LICENSE_SIGNATURE=...

Keep every line unchanged. Synthtraffic checks the file locally when an actual command starts.

Next

  • Quickstart — print three events on your machine