Quickstart

Install the SDK, program an FPGA, and run a real workload, in a few minutes, headless-friendly (no browser required if you'd rather use a token).

What you need

  • Python 3.12+
  • Docker, for local synth/PnR feedback and sandboxing (the SDK runs the pinned toolchain image for you, you never install yosys/nextpnr/LiteX)
  • An allowlisted API key for cloud FPGA access (mrg login)

1. Install

pip install manhattan-reasoning-gym
docker pull ghcr.io/manhattanreasoning/mrg-sandbox:latest

If your system Python is broken or externally managed, the robust path is uv venv && uv pip install manhattan-reasoning-gym.

2. Log in

mrg login

Opens a GitHub device-flow login in your browser and stores the resulting API key at ~/.config/mrg/credentials.json. Headless / CI environments can skip the browser entirely:

export MRG_API_KEY=...                        # already have a key
# or
mrg login --github-token <no-scope PAT>       # or $GITHUB_TOKEN

A no-scope personal access token is sufficient, it's only used to read your GitHub username against the allowlist.

3. Get a local build report: no board needed

mrg synth examples/design.py   # resource utilization, ~seconds
mrg pnr   examples/design.py   # Fmax + timing closure, ~tens of seconds

Both print a JSON report on stdout and exit non-zero if the build fails, useful in scripts and CI without ever touching a real board.

4. Run it on real hardware

mrg run examples/app.py

  ID  STATE           OWNER         CURRENT JOB
  ─────────────────────────────────────────────
   0  idle            -             -

mrg run submits the design, builds it (~2-3 min the first time), and flashes whichever board frees up first — no board is chosen up front, so which one you land on isn't known until the build finishes. The board stays reserved to you afterward; if the build is still in flight and you want to check on it from elsewhere, mrg jobs lists your jobs (a build with no board yet has nowhere else to be found). Free the board for someone else with:

mrg reset 0

reset is an async queued job that reflashes the base image (~1 min); poll with mrg status 0 rather than expecting it to complete instantly.

What's next