soldermaskdocs

Install

Install soldermask as a tool, or from a checkout if you want to change it. Then check that the router, KiCad and the model are found.

Requirements

NeedWhyNotes
Python 3.11+The pipeline and the appDeveloped on 3.13
GitHub access to soldermask-org/lightcycleLightcycle, the router, comes as a ready-built wheel from that private repositorysoldermask setup downloads it with your gh login or a GH_TOKEN. No Rust needed on macOS or Linux.
KiCad, for kicad-cliThe judge: KiCad's DRC checks the routed copper. It also renders the board and checks the schematic.Without it, no routed board can be GO. macOS: brew install --cask kicad. Ubuntu: the ppa:kicad/kicad-10.0-releases PPA.
ngspiceThe circuit simulationFound inside KiCad on macOS, or as the ngspice program or library. Without it, the board says it was not simulated.
A modelThe design stageClaude Code by default, logged in to claude.ai. Or a key: Gemini (SOLDERMASK_BACKEND=gemini) or Claude (SOLDERMASK_BACKEND=claude), with that backend's SDK
JLCPCB API credentialsOptional: stock and price from JLCPCB itself rather than a mirrorSee JLCPCB credentials
Internet on first useParts, footprints, symbols and 3D models are fetched, then cachedThe app's pages need no internet

Install as a tool

Use this when you only want to use soldermask.

The repository is private during the alpha

Request access and an invite is sent by hand. With access, gh auth login is enough for every step below.

  1. Sign in to GitHub with the account that has access: gh auth login.

  2. Install soldermask:

    uv tool install --with qrcode "git+https://github.com/ashwinsk01/soldermask.git@integration"

    --with qrcode lets the server print the QR code your phone scans. To design with a key instead of Claude Code, add --with google-genai for Gemini or --with anthropic for Claude.

  3. Install KiCad. On macOS:

    brew install --cask kicad
  4. Fetch what the package cannot carry. This downloads Lightcycle, fetches the KiCad symbols, and names anything still missing:

    soldermask setup

    The router line names the Lightcycle this soldermask pins, such as lightcycle-0.1.5 (Lightcycle). The kicad line gives the path to kicad-cli. setup exits with an error until it finds KiCad and at least one router.

    setup downloads Lightcycle through the gh command when it is signed in, or with a token in GH_TOKEN or GITHUB_TOKEN. An SSH key alone cannot download it. On a machine with no ready-built wheel, setup builds Lightcycle with cargo instead (rustup.rs). Add --astar to build the A* router as well. It needs git and cargo, and takes minutes.

  5. Install Claude Code, which designs the boards. Then log in once:

    claude          # log in with your claude.ai account, then quit
    # or use a key: export SOLDERMASK_BACKEND=gemini GEMINI_API_KEY=...
  6. Start the app, and open the address it prints:

    soldermask serve        # https://<your-lan-ip>:8443/

This installs integration, where new work lands, and these pages describe it. main moves only when integration is merged after CI passes on Python 3.11, 3.12 and 3.13. It can lag behind.

  • uv tool upgrade soldermask reinstalls from the branch's head. Run soldermask setup after every upgrade. It reinstalls Lightcycle when the version this soldermask pins has changed.
  • pipx install takes the same URL. Add the QR code with pipx inject soldermask qrcode.
  • git+ssh://git@github.com/... installs the same way as the HTTPS URL. soldermask setup still needs gh or a token.

pip install soldermask installs nothing useful

The name is reserved on public PyPI so nobody else takes it. That release contains no code.

Install from a checkout

Use this when you want to change soldermask.

git clone <your-remote> soldermask && cd soldermask
python3 -m venv .venv && .venv/bin/pip install -e ".[all]"
.venv/bin/pip install ./mould      # the compiled anneal; needs cargo
claude                             # log in once; or: export SOLDERMASK_BACKEND=gemini GEMINI_API_KEY=...
.venv/bin/soldermask setup         # Lightcycle's wheel and the KiCad symbols
.venv/bin/soldermask version       # soldermask 0.1.0+g<commit>  (project format 2)
.venv/bin/soldermask serve         # https://<your-lan-ip>:8443/

python3 must be 3.11 or newer. pip install -e . installs the package in place and gives you the soldermask command. pip install ./mould compiles the placer's anneal. Without it, the anneal runs in Python: the same placements, 40 to 160 times slower. CI installs the same way, with pip install -e . and then pip install ./mould. requirements.txt is not what CI installs, and it does not install soldermask itself.

The optional groups:

GroupAdds
geminiThe Gemini SDK
claudeThe Anthropic SDK
groqThe Groq SDK, for the command line's --backend groq
lanA QR code in the terminal for your phone
docsMkDocs, to build this manual for the app's /docs
learntorch, for training the routability model. Running the shipped model needs only numpy.
mouldThe compiled anneal and mould loop, built from source with cargo. A checkout runs pip install ./mould instead.
lightcycleLightcycle built from its private repository with cargo, at the pinned version. soldermask setup fetches the ready-built wheel instead.
allgemini, claude, groq, lan, docs and learn. Not mould or lightcycle.

Check the machine

Run soldermask setup --check. It fetches nothing, and prints what it found. That covers KiCad, Lightcycle, the symbols and the A* router. It also covers ngspice, the compiled anneal, the parts catalogue and where your data lives.

In the app, open About (/about) or call GET /api/app. Both say whether the model backend is reachable, whether the routers were found, and where projects are stored.

A missing router does not stop a build. With neither router installed, the board is placed and not routed. The gaps say so, and the poll's Route check reads stopped.

A missing KiCad does not stop a build either. Every fab file is still written. No DRC judges the copper, so a routed board cannot be GO. Where nothing else fails, its verdict is UNJUDGED.

JLCPCB credentials

These are optional. With them, stock and price come from JLCPCB's own API.

  1. Apply at api.jlcpcb.com and create an app.
  2. Request the Parts API for that app.
  3. Set JLCPCB_APP_ID, JLCPCB_ACCESSKEY and JLCPCB_SECRETKEY in the environment.
  4. Run soldermask setup --check. It says whether the app has been granted the API.

Where things live

Installed fromProjectsCaches
A checkoutprojects/ next to the code.cache/ next to the code
A tool install, macOS~/Library/Application Support/soldermask/projects~/Library/Application Support/soldermask/.cache
A tool install, elsewhere$XDG_DATA_HOME/soldermask/projects (default ~/.local/share)$XDG_DATA_HOME/soldermask/.cache

Set SOLDERMASK_HOME to move both, or SOLDERMASK_PROJECTS and SOLDERMASK_CACHE to move each one. soldermask setup --check prints where they are. See Configuration.

On this page