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
| Need | Why | Notes |
|---|---|---|
| Python 3.11+ | The pipeline and the app | Developed on 3.13 |
GitHub access to soldermask-org/lightcycle | Lightcycle, the router, comes as a ready-built wheel from that private repository | soldermask setup downloads it with your gh login or a GH_TOKEN. No Rust needed on macOS or Linux. |
KiCad, for kicad-cli | The 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. |
| ngspice | The circuit simulation | Found inside KiCad on macOS, or as the ngspice program or library. Without it, the board says it was not simulated. |
| A model | The design stage | Claude 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 credentials | Optional: stock and price from JLCPCB itself rather than a mirror | See JLCPCB credentials |
| Internet on first use | Parts, footprints, symbols and 3D models are fetched, then cached | The 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.
-
Sign in to GitHub with the account that has access:
gh auth login. -
Install soldermask:
uv tool install --with qrcode "git+https://github.com/ashwinsk01/soldermask.git@integration"--with qrcodelets the server print the QR code your phone scans. To design with a key instead of Claude Code, add--with google-genaifor Gemini or--with anthropicfor Claude. -
Install KiCad. On macOS:
brew install --cask kicad -
Fetch what the package cannot carry. This downloads Lightcycle, fetches the KiCad symbols, and names anything still missing:
soldermask setupThe
routerline names the Lightcycle this soldermask pins, such aslightcycle-0.1.5 (Lightcycle). Thekicadline gives the path tokicad-cli.setupexits with an error until it finds KiCad and at least one router.setupdownloads Lightcycle through theghcommand when it is signed in, or with a token inGH_TOKENorGITHUB_TOKEN. An SSH key alone cannot download it. On a machine with no ready-built wheel,setupbuilds Lightcycle withcargoinstead (rustup.rs). Add--astarto build the A* router as well. It needs git and cargo, and takes minutes. -
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=... -
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 soldermaskreinstalls from the branch's head. Runsoldermask setupafter every upgrade. It reinstalls Lightcycle when the version this soldermask pins has changed.pipx installtakes the same URL. Add the QR code withpipx inject soldermask qrcode.git+ssh://git@github.com/...installs the same way as the HTTPS URL.soldermask setupstill needsghor 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:
| Group | Adds |
|---|---|
gemini | The Gemini SDK |
claude | The Anthropic SDK |
groq | The Groq SDK, for the command line's --backend groq |
lan | A QR code in the terminal for your phone |
docs | MkDocs, to build this manual for the app's /docs |
learn | torch, for training the routability model. Running the shipped model needs only numpy. |
mould | The compiled anneal and mould loop, built from source with cargo. A checkout runs pip install ./mould instead. |
lightcycle | Lightcycle built from its private repository with cargo, at the pinned version. soldermask setup fetches the ready-built wheel instead. |
all | gemini, 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.
- Apply at api.jlcpcb.com and create an app.
- Request the Parts API for that app.
- Set
JLCPCB_APP_ID,JLCPCB_ACCESSKEYandJLCPCB_SECRETKEYin the environment. - Run
soldermask setup --check. It says whether the app has been granted the API.
Where things live
| Installed from | Projects | Caches |
|---|---|---|
| A checkout | projects/ 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.