SuperSynth

SuperSynth is a cloud FPGA synthesis platform. Upload your HDL source code, and SuperSynth runs the open-source FPGA toolchain (Yosys, nextpnr, icepack/ecppack) in parallel across multiple seeds to find the best result.

What it does

1. Upload your Verilog, SystemVerilog, or VHDL source
2. Synthesize across multiple seeds in parallel
3. Pick the winner by timing or area
4. Download the bitstream and build reports

SuperSynth handles the compute, queueing, and toolchain management. You get back a bitstream and quality-of-results metrics.

Ways to use it

• Web interface at supersynth.ai — create projects, submit jobs, view logs and results
• CLI (ssynth) — submit jobs from your terminal or CI pipeline
• REST API — integrate directly into your tooling

Supported FPGA families

Key features

• Multi-seed search: Run 1-32 seeds in parallel, pick the best by timing or area
• Streaming logs: Watch synthesis output in real time (web or CLI)
• Artifact management: Download bitstreams, netlists, and reports
• Project organization: Group jobs under projects with default settings
• API keys: Authenticate CI pipelines and scripts
• Credit-based billing: Pay for what you use

Quick Start

Web

1. Sign in at supersynth.ai with your GitHub account
2. Create a project (give it a slug and display name)
3. Click New Job, select a target, enter your top module name, upload your source
4. Watch the logs stream in real time
5. Download the bitstream from the Artifacts tab

CLI

# Install
cargo install --git https://github.com/ACS-Org/ssynth-cli

# Authenticate (get an API key from Settings > API Keys in the web UI)
ssynth login --api-key sk_live_YOUR_KEY

# Create a project
ssynth project create --slug my-fpga --name "My FPGA Project"

# Submit a job
ssynth job submit ./src --project <PROJECT_ID> --target ice40:hx8k:ct256 --top top_module

# Watch it run
ssynth job logs <JOB_ID> --follow

# Download results
ssynth artifact download <JOB_ID>

With hwbuild.yml

Put a hwbuild.yml in your project root to avoid repeating CLI flags:

top_module: top
target:
  family: ice40
  device: hx8k
  package: ct256
seeds: 4
pick: best_timing

Then submit with just:

ssynth job submit . --project <PROJECT_ID>

See hwbuild.yml reference for all options.

Concepts

Projects

A project groups related synthesis jobs. Each project has:

• A slug (URL-safe identifier, e.g., my-counter)
• A display name
• Optional defaults: target, max runtime, max memory, archive format, retention period

Jobs

A job is a single synthesis request. You provide source code, a target FPGA, and parameters. SuperSynth creates one run per seed and executes them in parallel.

Job statuses: created → queued → running → completed | failed | canceled | terminated

A job is terminated if it exceeds its time limit. A job is canceled if you cancel it manually.

Runs and Seeds

Each job fans out into one or more runs, each with a different random seed. The FPGA place-and-route tool uses this seed to explore different placement options. More seeds = better chance of finding a good result.

After all runs complete, a winner is selected based on the pick strategy (best_timing or best_area).

Pipeline Steps

Each run executes up to three steps:

You can run a subset (e.g., synth only) for quick validation.

Targets

A target identifies a specific FPGA device and package. Format: family:device:package.

Examples: ice40:hx8k:ct256, ecp5:85k:CABGA554

See FPGA Targets for the full list.

Credits

SuperSynth uses a credit-based billing model. Each run consumes credits based on compute time. Check your balance at Settings > Billing in the web UI, or via ssynth usage in the CLI.

API Keys

API keys (sk_live_...) authenticate the CLI and API integrations. Create them in Settings > API Keys. Keys are shown once at creation — save them immediately.

FPGA Targets

List available targets with ssynth targets or the Targets tab on any project page.

iCE40 Family

Open-source toolchain: Yosys + nextpnr-ice40 + icepack.

ECP5 Family

Open-source toolchain: Yosys + nextpnr-ecp5 + ecppack.

Supported HDL Languages

Mixed Verilog/VHDL projects are supported. VHDL files are processed with GHDL before Yosys synthesis.

Constraint Files

Authentication (Web)

Sign in with GitHub

1. Go to supersynth.ai
2. Click Sign In or Get Started
3. Click Sign in with GitHub
4. Authorize SuperSynth on GitHub
5. You’re redirected to the dashboard

On first login, a tenant and user account are created automatically from your GitHub profile.

Sessions

Your session lasts 1 hour. The browser automatically refreshes the token in the background. If your session expires, you’ll be redirected to the login page.

Signing out

Click your avatar in the top bar, then Logout. This revokes your session token.

Projects (Web)

Creating a project

1. From the dashboard, click New Project
2. Enter a slug (lowercase, hyphens, used in URLs) and a display name
3. Optionally select a default target
4. Click Create

Project page

The project page has three tabs:

Jobs tab

Lists all jobs in the project, newest first. Filter by status: All, Created, Queued, Running, Completed, Failed, Canceled, Terminated.

Click New Job to submit a synthesis job (see Submitting Jobs).

Targets tab

Read-only list of available FPGA targets. Shows family, device, package, board, and toolchain lane for each.

Settings tab

Configure project defaults:

• Display name
• Retention period — how long to keep artifacts (7, 30, or 90 days)
• Default max runtime — time limit for jobs
• Default max memory — memory limit for jobs

These defaults apply to new jobs unless overridden at submission time.

Submitting Jobs (Web)

Create a job

1. Navigate to a project
2. Click New Job
3. Fill in the required fields:
   • Target — select an FPGA target
   • Top Module — name of your top-level Verilog/VHDL module
   • Source — drag-and-drop or browse for a .tar.gz or .zip archive of your HDL source

Advanced options

Expand the Advanced section to configure:

4. Click Create Job

You’re taken to the job detail page where you can watch progress in real time.

Source archives

Package your HDL source as a .tar.gz or .zip file. Include:

• All Verilog/SystemVerilog/VHDL source files
• Constraint files (.pcf, .lpf) if needed
• A hwbuild.yml is not required for web submissions (parameters are set in the form)

The archive should contain source files at the top level or in subdirectories. SuperSynth discovers .v, .sv, .vhd, and .vhdl files recursively.

Job Results (Web)

Job detail page

After submitting a job, you land on the job detail page. The header shows:

• Status badge (queued, running, completed, failed, etc.)
• Job ID, creation time, and total duration
• Action buttons: Cancel (if running), Retry, Clone

Tabs

Timeline

Shows the winning run’s pipeline steps (synth, pnr, bitstream) with start/end times and durations. Visible once a winner is selected.

Logs

Real-time log output streamed via WebSocket. The first lines contain a Build Environment block showing worker hostname, container ID, OS version, worker version, run/job/seed context, target info, and toolchain versions (yosys, ghdl, nextpnr, icepack, ecppack). This metadata aids reproducibility and debugging. Synthesis, place-and-route, and bitstream generation output follows. After the job completes, full logs remain available.

QoR (Quality of Results)

Summary metrics for the winning run:

• Timing: Fmax (maximum frequency achieved)
• Area: LUT utilization, register count
• Critical path details

Also shows a download command for the build archive.

Seeds

Visible when the job has multiple seeds. Shows a table comparing all runs: seed number, status, Fmax, LUT count, and whether it’s the winner.

Artifacts

• Download Build Archive button — downloads the full archive (.tar.gz or .zip)
• Artifact table: lists individual files (bitstream, netlist, logs, reports) with type, filename, size, and SHA-256 checksum

Job actions

Cancel

Stops all in-flight runs. Available while the job is queued or running.

Retry

Re-runs failed seeds (or all seeds). Creates new runs under the same job.

• Failed only — retry seeds that failed or were terminated
• All — retry every seed

Clone

Creates a new job with the same source and parameters. You can override seeds, parallelism, priority, strategy, or target.

Settings & API Keys (Web)

Navigate to Settings from the sidebar.

API Keys

Create keys for CLI and API access.

1. Click New API Key
2. Enter a name (e.g., “laptop”, “ci-pipeline”)
3. Copy the key immediately — it starts with sk_live_ and is shown only once
4. Use it with the CLI: ssynth login --api-key sk_live_...
5. Or set the x-api-key header in API calls

To revoke a key, click Revoke next to it. Revoked keys stop working immediately.

Maximum 25 API keys per account.

Billing

Shows your credit balance, current plan, and recent transactions.

Usage

Credit consumption history and usage breakdown.

Retention

Configure how long artifacts are kept before automatic cleanup.

Installation

From source (Rust)

cargo install --git https://github.com/ACS-Org/ssynth-cli

Requires Rust 1.75+.

Verify

ssynth --version

Configuration

Config is stored at ~/.config/ssynth/config.toml (permissions 0600). Created automatically on first ssynth login.

You can override the API URL:

# Flag (highest priority)
ssynth --api-url https://api.example.com targets

# Environment variable
export SSYNTH_API_URL=https://api.example.com

# Config file (lowest priority)
# api_url = "https://api.supersynth.ai"

Authentication (CLI)

Login with an API key

1. Create an API key in the web UI at Settings > API Keys
2. Run:

ssynth login --api-key sk_live_YOUR_KEY

Or omit the flag to be prompted:

ssynth login
# API Key: (paste key, hidden)

On success, the key is stored in ~/.config/ssynth/config.toml and your default tenant is set automatically.

Environment variable

Skip the config file entirely:

export SSYNTH_API_KEY=sk_live_YOUR_KEY
ssynth targets

The environment variable takes priority over the config file.

Verify

ssynth config show   # shows stored auth and tenant
ssynth targets       # quick smoke test

Dev login (local development only)

When the API has DEV_AUTH_BYPASS=true:

ssynth login --dev --username myname

This uses a short-lived JWT instead of an API key. Not available in production.

hwbuild.yml

Place a hwbuild.yml in your project root to define default synthesis parameters. The CLI reads it automatically when you ssynth job submit a directory.

All CLI flags override hwbuild.yml values.

Example

top_module: top
target:
  family: ice40
  device: hx8k
  package: ct256
constraints:
  - pins.pcf
seeds: 4
pick: best_timing
priority: standard
parallelism: 2
steps:
  - synth
  - pnr
  - bitstream
max_runtime: "2h"
max_memory: "8GB"

Fields

Target resolution order

1. CLI --target flag
2. hwbuild.yml target section
3. Project’s default target
4. Error if none specified

Submitting Jobs (CLI)

From a directory

ssynth job submit ./my-project --project <PROJECT_ID> --top top_module --target ice40:hx8k:ct256

The CLI bundles the directory into a .tar.gz, uploads it, and creates the job. Files matching .gitignore patterns are excluded.

From an archive

ssynth job submit my-design.tar.gz --project <PROJECT_ID> --top top_module --target ecp5:85k:CABGA554

Accepts .tar.gz and .zip files.

With hwbuild.yml

If your directory contains a hwbuild.yml, the CLI reads target, top module, and other settings from it:

ssynth job submit . --project <PROJECT_ID>

See hwbuild.yml for the format.

Common options

ssynth job submit ./src \
  --project <PROJECT_ID> \
  --target ice40:hx8k:ct256 \
  --top counter \
  --seeds 8 \
  --pick best_timing \
  --priority interactive \
  --parallelism 4 \
  --steps synth,pnr,bitstream \
  --max-runtime 2h \
  --max-memory 8GB

Wait for completion

Add --wait to stream logs until the job finishes:

ssynth job submit . --project <PROJECT_ID> --wait

Idempotency

Use --idempotency-key to prevent duplicate submissions:

ssynth job submit . --project <PROJECT_ID> --idempotency-key "commit-abc123"

If a job with the same key already exists, the existing job is returned instead of creating a new one.

Setting a default project

To avoid passing --project every time:

export SSYNTH_PROJECT=<PROJECT_ID>
ssynth job submit .

Or set defaults.project_id in ~/.config/ssynth/config.toml.

Managing Jobs (CLI)

Job status

ssynth job status <JOB_ID>

Shows status, run counts, step details, and winner info. Add --watch to refresh every 5 seconds:

ssynth job status <JOB_ID> --watch

List jobs

ssynth job list
ssynth job list --status running
ssynth job list --project <PROJECT_ID> --limit 10

Logs

View historical logs:

ssynth job logs <JOB_ID>
ssynth job logs <JOB_ID> --offset 100 --limit 50

Stream logs in real time:

ssynth job logs <JOB_ID> --follow

Cancel

ssynth job cancel <JOB_ID>

Stops all in-flight runs immediately.

Retry

Re-run failed seeds:

ssynth job retry <JOB_ID>
ssynth job retry <JOB_ID> --scope all   # retry all seeds, not just failed

Clone

Create a new job from an existing one, with optional overrides:

ssynth job clone <JOB_ID>
ssynth job clone <JOB_ID> --seeds 16 --priority batch

Download artifacts

List artifacts:

ssynth artifact list <JOB_ID>

Download the build archive:

ssynth artifact download <JOB_ID>
ssynth artifact download <JOB_ID> --output-dir ./builds

Projects & Targets (CLI)

Projects

List projects:

ssynth project list

Create a project:

ssynth project create --slug my-fpga --name "My FPGA Project"
ssynth project create --slug my-fpga --name "My FPGA Project" --target ice40:hx8k:ct256

View details:

ssynth project get <PROJECT_ID>

Update:

ssynth project update <PROJECT_ID> --name "New Name"
ssynth project update <PROJECT_ID> --retention-days 30

Delete:

ssynth project delete <PROJECT_ID>

Targets

List all available FPGA targets:

ssynth targets

Output includes family, device, package, and board for each target.

API keys

Create:

ssynth api-key create --name "ci-pipeline"
ssynth api-key create --name "expires-eoy" --expires-at 2026-12-31

The full key is shown once. Save it immediately.

List:

ssynth api-key list

Revoke:

ssynth api-key revoke <KEY_ID>

Usage

Check credit balance and recent usage:

ssynth usage

JSON output

Add --json to any command for machine-readable output:

ssynth job list --json
ssynth project list --json | jq '.[0].id'

Command Reference

Global flags

ssynth login

ssynth login [--api-key <KEY>] [--dev] [--username <NAME>]

ssynth job submit

ssynth job submit <PATH> [OPTIONS]

ssynth job status

ssynth job status <JOB_ID> [--watch]

ssynth job list

ssynth job list [--status <STATUS>] [--project <ID>] [--limit <N>]

ssynth job logs

ssynth job logs <JOB_ID> [--follow] [--offset <N>] [--limit <N>]

ssynth job cancel

ssynth job cancel <JOB_ID>

ssynth job retry

ssynth job retry <JOB_ID> [--scope failed|all]

ssynth job clone

ssynth job clone <JOB_ID> [--seeds <N>] [--parallelism <N>] [--priority <LEVEL>] [--pick <STRATEGY>] [--target <ID>]

ssynth artifact list

ssynth artifact list <JOB_ID>

ssynth artifact download

ssynth artifact download <JOB_ID> [--output-dir <DIR>]

ssynth project list / create / get / update / delete

ssynth project list
ssynth project create --slug <SLUG> --name <NAME> [--target <ID>]
ssynth project get <ID>
ssynth project update <ID> [--name <NAME>] [--retention-days <N>]
ssynth project delete <ID>

ssynth api-key create / list / revoke

ssynth api-key create --name <NAME> [--expires-at <ISO-DATE>]
ssynth api-key list
ssynth api-key revoke <ID>

ssynth targets

ssynth targets

ssynth usage

ssynth usage

ssynth config show

ssynth config show