Install
Requirements
| Need | Why | Notes |
|---|---|---|
| Python 3.11+ | the pipeline and the app | 3.13 is what it is developed on |
| Java 25+ | the autorouter is freerouting, a Java program | brew install openjdk on macOS; the macOS /usr/bin/java stub does not count and is detected as such |
freerouting-2.4.1.jar | the router itself | not in the repository and not in the wheel (64 MB, and the jar carries GPL text). soldermask setup fetches it and checks its SHA-256; in a checkout you can equally drop it in vendor/ yourself (gh release download v2.4.1 -R freerouting/freerouting -p freerouting-2.4.1.jar -D vendor/) |
| A model API key | the design stage | Gemini by default (GEMINI_API_KEY), or Claude (SOLDERMASK_BACKEND=claude) |
| JLCPCB API credentials, optional | stock and price from JLCPCB itself rather than a mirror | apply at api.jlcpcb.com, create an app, request the Parts API for it, then JLCPCB_APP_ID, JLCPCB_ACCESSKEY, JLCPCB_SECRETKEY in the environment; soldermask setup --check says whether the app is granted |
| Internet on first use | parts, footprints, symbols and 3D models are fetched and cached | the app pages themselves need no internet |
Steps
As a tool, when you only want to use it. The repository is private while
soldermask is in alpha: request access
and an invite is sent by hand. With access, gh auth login or an SSH key is
enough, and git+ssh://git@github.com/... works the same way:
uv tool install git+https://github.com/ashwinsk01/soldermask
soldermask setup --astar # the router's jar, the KiCad symbols, the A* router; says what is missing
export GEMINI_API_KEY=... # or: export SOLDERMASK_BACKEND=claude ANTHROPIC_API_KEY=...
soldermask serve # https://<your-lan-ip>:8443/That installs main, which only moves once CI has passed on 3.11, 3.12 and
3.13; the work lands on integration first, and
uv tool install "git+https://github.com/ashwinsk01/soldermask@integration"
takes it from there. uv tool upgrade soldermask re-installs from the branch's head; pipx install takes the same URL. pip install soldermask from public PyPI gets you
nothing — the name is reserved there so nobody else takes it, and that
release deliberately contains no code.
From a checkout, when you want to change it:
git clone <your-remote> soldermask && cd soldermask
python3 -m venv .venv && .venv/bin/pip install -e ".[all]"
export GEMINI_API_KEY=... # or: export SOLDERMASK_BACKEND=claude ANTHROPIC_API_KEY=...
.venv/bin/soldermask version # soldermask 0.1.0 (project format 2)
.venv/bin/soldermask serve # https://<your-lan-ip>:8443/pip install -e . installs the package in place and gives you the soldermask command. The optional groups are gemini, claude, lan (QR code in the terminal), learn (torch, for training the routability model — running the shipped one needs only numpy) and all. requirements.txt is the exact frozen environment the project is verified with, if you prefer pip install -r requirements.txt.
Check the machine
Open About in the app (/about) or call GET /api/app. It tells you whether the model backend is reachable, whether Java and the router jar were found, and where projects are stored. A missing router does not stop a build — the board is saved unrouted and the Route readout says so.
Where things live
From a checkout, projects go in projects/ next to the code and caches in .cache/. Installed there is no "next to the code" to write to — site-packages is not yours — so both move under ~/Library/Application Support/soldermask on macOS and $XDG_DATA_HOME/soldermask (default ~/.local/share/soldermask) elsewhere. Set SOLDERMASK_HOME to move both, or SOLDERMASK_PROJECTS / SOLDERMASK_CACHE individually. soldermask setup --check prints where they landed. See Configuration.