Configuration
soldermask is set up with environment variables and a few flags on the serve command. There is no config file.
Where things live
| Variable | Default | What it sets |
|---|---|---|
SOLDERMASK_HOME | The repository in a checkout. Otherwise ~/Library/Application Support/soldermask on macOS, or $XDG_DATA_HOME/soldermask (~/.local/share/soldermask) elsewhere. | The base directory. projects/ and .cache/ sit under it. |
SOLDERMASK_PROJECTS | $SOLDERMASK_HOME/projects | The projects directory |
SOLDERMASK_CACHE | $SOLDERMASK_HOME/.cache | The cache: parts, footprints, symbols, 3D models, the certificate and the access token |
SOLDERMASK_CORPUS | $SOLDERMASK_CACHE/corpus | Every route the pipeline runs, kept as training data |
SOLDERMASK_DOCS | <repo>/site | The built manual the app serves at /docs |
The model
The default backend, claude-code, needs no key. It needs the claude command
on PATH, logged in with a claude.ai account. It ignores ANTHROPIC_API_KEY,
so a key never bills its turns.
| Variable | Default | What it sets |
|---|---|---|
SOLDERMASK_BACKEND | claude-code | The design model: claude-code, gemini, claude, groq or mercury. SILIXON_BACKEND is still read. |
SOLDERMASK_CLAUDE_CODE_MODEL | claude-fable-5-2 | The model the claude-code backend asks for |
SOLDERMASK_CLAUDE_CODE_TIMEOUT_S | 900 | How long one claude-code turn may take, in seconds |
GEMINI_API_KEY or GOOGLE_API_KEY | none | Gemini credentials |
ANTHROPIC_API_KEY | none | Credentials for the claude backend. A logged-in ant auth profile also works. |
GROQ_API_KEY | none | Groq credentials |
GROQ_MAX_OUTPUT_TOKENS | 16000 | The most output tokens one Groq call asks for |
INCEPTION_API_KEY | none | Credentials for the mercury backend |
TYPESAFE_API_KEY | none | Jev's key, for the last rung of pin-name resolution. It may also sit in .env in the home directory, or in .cache/typesafe.key. See Jev. |
SOLDERMASK_GEMINI_TIMEOUT_S | 600 | How long one Gemini call may take, in seconds |
SOLDERMASK_AUTO_REPAIR | 1 | Rounds of revision for a chat turn whose build fails its checks. 0 turns it off. |
SOLDERMASK_MODEL_CALLS | on | none (or 0, off) stops the pipeline calling a model of its own: no datasheet pin table is transcribed and Jev is not asked. soldermask mcp sets it unless given --model-calls. |
With auto-repair on, a turn whose build has unresolved parts or electrical errors goes back to the model. The revision is kept only if it scores better.
The datasheet reader
The reader writes a part's datasheet record with two Azure models when you ask it to. It is off by default.
Pin tables are a separate read
For a part with a vendor symbol of four or more pins, a build fetches the datasheet.
The design model then transcribes its pin table, once a part, with the reader on or off.
SOLDERMASK_MODEL_CALLS=none stops both. See Datasheet names.
| Variable | Default | What it sets |
|---|---|---|
SOLDERMASK_DATASHEET_READER | off | azure turns the reader on, for read_datasheet and soldermask parts read only. A build never runs it on its own. |
SOLDERMASK_READER_MAX_USD | 0.50 | The most one read may cost, in US dollars at list price. A read stops before a call that could pass it, and stores nothing. |
SOLDERMASK_READER_DRAW | off | on or gpt-5.4-mini adds read C, the drawing read. gpt-6-luna is the cheaper model. Read C confirms a value read off a figure. |
AZURE_AI_KEY | none | The Azure key. It may also sit in .env under the home directory. Without one, the reader asks the az command line. |
SOLDERMASK_READER_AZURE_RESOURCE | soldermask-astra/soldermask-astra-e2 | The resource group and account az reads the key from |
SOLDERMASK_READER_ENDPOINT or AZURE_AI_ENDPOINT | https://soldermask-astra-e2.cognitiveservices.azure.com | Where the two models are served |
A read uses DeepSeek-V4.1-Flash and gpt-5.4, and cost about $0.07 a sheet on
60 test parts. Read C adds gpt-5.4-mini, about $0.007 a sheet it reads, and
runs only when a figure value needs it. Records go to components/ in the
cache. A record in the shipped library always wins over one the reader wrote.
See MCP server.
Serving
| Variable or flag | What it sets |
|---|---|
SOLDERMASK_TOKEN | The access token. off, none or 0 turns access control off, like --no-auth. |
--token, --no-auth, --proxy, --workers, --log-file, --http, --port, --host | See Command line |
SOLDERMASK_MCP_KEYS, SOLDERMASK_MCP_PROJECTS, SOLDERMASK_MCP_BUILDS | The MCP server over HTTP. See MCP server. |
SOLDERMASK_MCP_LOG | A file the MCP server appends one JSON line a tool call to, over stdio or HTTP. Unset, nothing is logged. |
Services
| Variable | Default | What it sets |
|---|---|---|
JLCPCB_APP_ID, JLCPCB_ACCESSKEY, JLCPCB_SECRETKEY | none | JLCPCB API credentials, for the catalogue, stock and price from JLCPCB itself. soldermask setup --check says whether the app is granted the Parts API. |
JLCPCB_ENDPOINT | https://open.jlcpcb.com | Where JLCPCB's API is served |
GH_TOKEN or GITHUB_TOKEN | none | A GitHub token soldermask setup downloads Lightcycle with, when the gh command is not signed in |
The terminal
| Variable | What it sets |
|---|---|
NO_COLOR | Turns colour off, and with it the board's picture |
FORCE_COLOR | Turns colour on, even into a pipe |
COLORTERM | truecolor or 24bit gives the 24-bit orange; otherwise the nearest of 256 colours |
TERM | dumb turns colour off |
Building
| Variable | Default | What it sets |
|---|---|---|
SOLDERMASK_ROUTER | lightcycle | The first router for a design that names none: lightcycle or krt (the A* router). A design's own rules.router wins. |
SOLDERMASK_ANNEAL_WORKERS | One a core under the CLI, the app, soldermask mcp --http and soldermask.evaluate; 1 in the library and the stdio MCP server | Placements annealed at once |
SOLDERMASK_ROUTE_WORKERS | 3 on 32 cores or more, else 1 | Placements routed at once |
SOLDERMASK_ROUTE_PROCESSES | on | Placements routed at once each run in a process of their own, where the program allows worker processes. The first clean one stops the rest. 0 uses threads |
SOLDERMASK_ROUTE_RACE_NICE | 10 | How far down raced placements after the first run, so they use spare cores only. 0 runs them all at one priority |
SOLDERMASK_ROUTER_RETRY_WORKERS | One a core under the CLI, the app, soldermask mcp --http and soldermask.evaluate; 1 in the library and the stdio MCP server | Lightcycle retries of a short board solved at once. The copper is the same; it takes more CPU |
SOLDERMASK_ROUTER_WALL_S | 600 | Seconds a whole-board Lightcycle route may run before it is stopped. The route is then left undone and the gaps say so. Applies where the program allows worker processes. 0 turns it off |
SOLDERMASK_ANNEAL | auto | The anneal loop: auto (compiled when built), python, or rust (an error if not built) |
SOLDERMASK_MOULD | auto | The mould's loop: auto, or numpy to force the reference |
SOLDERMASK_MOULD_THREADS | 0 (all) | Threads for the compiled mould |
SOLDERMASK_SPACING_MM | 0.5 | Air between parts, in mm. 0 packs courtyards together; auto works it out from the board's room. |
SOLDERMASK_PRECEDENT | 1 | 0 stops a corpus board seeding the anneal |
SOLDERMASK_SIM | on | 0 skips the simulation stage |
SOLDERMASK_NGSPICE | ngspice on PATH | The ngspice program, or libngspice |
SOLDERMASK_OFFLINE | off | 1 stops every network call. A cache miss is then a miss. |
SOLDERMASK_PARTS | jlcparts | jlcsearch resolves parts, and checks their stock, through jlcsearch instead of the local catalogue. Only then is stock marked live; otherwise it is catalogue stock. |
SOLDERMASK_KRT, SOLDERMASK_KRT_PYTHON | .cache/krt, .cache/krtenv/bin/python | The A* router's checkout and its Python |
Experiment switches
These change the pipeline for a measurement. The defaults are what ships.
| Variable | Default | What it changes |
|---|---|---|
SOLDERMASK_MOVES_PER_PART | 8000 | Anneal moves per free part. 0 gives the old fixed 20,000 steps. |
SOLDERMASK_ROT360 | 1 | A turn picks 90, 180 or 270 degrees. 0 keeps every part at 0 or 90. |
SOLDERMASK_SWAP_P | 0.1 | How often the anneal swaps two parts. 0 turns swaps off. |
SOLDERMASK_ANTENNA_KEEPOUT | 1 | 0 stops the placer charging for parts under a module's antenna |
SOLDERMASK_ESD_W | 4 | Weight pulling ESD parts to the connector they guard; 0 turns it off |
SOLDERMASK_PADACCESS_W | 0 (off) | Weight charging a pad beside another part's mounting hole that no track can reach. 20 turns it on. See Pads beside a hole. |
SOLDERMASK_MASK_CLAIM | 1 | On a board read from a file, one net may cross a solder-mask window over no pad, and a zero-width mask line is no obstacle. 0 makes every such window a wall again. |
SOLDERMASK_MASK_SHARED | 1 | The nets whose pads sit in a shared mask window may cross it to reach them. 0 makes the window a wall for every net. |
SOLDERMASK_UNSTARVE | 1 | A ground pad the pour reaches by one thermal spoke is joined to it solid, where KiCad finds the board no worse. 0 keeps every relief. |
SOLDERMASK_EP_VIAS | 1 | When the route leaves a QFN's or DFN's exposed pad short, it runs again with a via at the pad's centre. The better route is kept. 0 routes without it. |
SOLDERMASK_DESIGN_CHECK | on | 0 turns off the design check, which holds a board to its parts' datasheet records. Its errors fail the verdict. See The design check. |
SOLDERMASK_LAYOUT_RULES | 1 | 0 stops the build checking datasheet layout rules. They are advice and never change the verdict. See Datasheet layout rules. |
SOLDERMASK_LAYOUT_RULES_FILE | soldermask/assets/layout_rules.json | Another rules file to check against. A missing file checks nothing. |
SOLDERMASK_SIZE_TARGET | 0.45 | The share of the board a roomy board's parts are cut down to cover, at most 0.45. 0 turns the sizer off. See When the board is too big. |
SOLDERMASK_FINE_RING_MM | 0 (off) | A ring of room around fine-pitch parts, in mm |
SOLDERMASK_POWER_POUR | unset | 1 pours the power nets the pipeline picks, 0 pours none, or a comma-separated list of nets |
SOLDERMASK_POWER_FALLBACK | on | A board whose copper alone fails is built again with its power nets poured, and the better build is kept. 0 builds once |
SOLDERMASK_POWER_SHAPE | unset | A power pour's outline: hull, tree or mould |
SOLDERMASK_GROUND_FIRST | off | 1 gives every surface ground pad a via before signals route |
SOLDERMASK_DECAP_SITES | off | 1 gives each decoupling capacitor's ground pad, and its chip's ground pins, a via before signals route |
SOLDERMASK_SIGNALS_FIRST | swap | Where the ground vias laid before routing left a signal open, route the signals first and lay the vias clear of them. Both boards are poured, side by side where worker processes are allowed, and the one with fewer connections missing is kept. room moves only the vias in a closed net's way. off turns it off |
SOLDERMASK_ESCAPE | on | Lays a straight escape stub out of each pad Lightcycle's grid cannot end on, before each placement is routed. Only a board Lightcycle routes first gets them. 0 turns it off |
SOLDERMASK_SITE_COPPER | on | The router keeps the clearance and the hole rules from a ground via laid before routing, as from any via. 0 hands it the old square instead |
SOLDERMASK_POUR_PARALLEL | 1 | 0 runs the pour's fallback route after the main one, not beside it |
SOLDERMASK_POUR_EP_SITES | 1 | A QFN's or DFN's exposed pad on the poured ground gets a via at its centre before routing, so the fill reaches it. 0 leaves it to the fill and the fallback |
SOLDERMASK_FANOUT | off | stub or underpad escapes fine-pitch pads before the A* router |
SOLDERMASK_TANDEM | 1 | 0 stops Lightcycle routing every placement to rank them |
SOLDERMASK_TANDEM_MORE | 3 | Fresh placements annealed and routed when none of the first reaches every pin. 0 adds none |
SOLDERMASK_ROUTER_RETRY | on | 0 stops a short board's retries after the finer grid, so the three other settings are not tried |
SOLDERMASK_ROUTER_RETRY_SHORT | 2 | The other settings are tried only on a board this many pins short or fewer |
SOLDERMASK_ROUTER_RETRY_GRID_SHORT | 6 | The finer grid is tried only on a board this many pins short or fewer. 0 tries it on every short board |
SOLDERMASK_ROUTER_RETRY_GRID_KEEP | off | 1 also tries the finer grid on the pour's re-route around copper it keeps |
SOLDERMASK_ROUTER_NECK_MM | 1.0 | How far from a pad a wide net may narrow to the width the pad takes, in mm. 0 leaves such a pad open, and the gaps say so |
SOLDERMASK_ROUTER_THREADS | 1 | Lightcycle threads for nets that do not meet |
SOLDERMASK_ROUTER_PRES0 | 0.6 | The congestion price Lightcycle starts at. Higher ends in fewer rounds and more vias |
SOLDERMASK_ROUTER_PRES_GROW | 1.4 | How much that price grows each round |
SOLDERMASK_ROUTER_BRANCHES | 1 | 0 makes Lightcycle reroute whole nets |
SOLDERMASK_LC_EXACT | off | 1 asks Lightcycle for exact margins. Copper may then sit at the board's rule beside a pad, rather than half a grid step further off |
SOLDERMASK_ROUTER_THIN | 0.5,0 | Width caps for a short board's thin route, in mm; 0 is the board's track; empty turns it off |
SOLDERMASK_ROUTER_THIN_RANK | 1 | 0 keeps the thin route out of the pass that ranks placements; faster, and it closed fewer motor boards |
SOLDERMASK_ROUTER_POWER_FIRST | 0 | 1 routes a short board's wide nets alone first, then the rest round them; experimental |
SOLDERMASK_ROUTER_POWER_FIRST_MM | 0.5 | With SOLDERMASK_ROUTER_POWER_FIRST=1, the nets wider than this, in mm, are routed first |
SOLDERMASK_ROUTER_UPGRADE | 12 | How many warm nets of a thin route are routed again alone, wider |
SOLDERMASK_WIDEN_SHOULDERS | 1 | 0 widens a thin route's tracks about their centre only |
SOLDERMASK_WARM_C | 20 | A narrow run this many °C over the room is a gap |
SOLDERMASK_HOT_C | 100 | A narrow run this many °C over the room fails the verdict |
SOLDERMASK_PAIRS | 1 | 0 routes a differential pair's two nets as two nets, not side by side |
SOLDERMASK_PAIRS_IN2 | 0 | 1 lets a four-layer board lay a pair's middle on In2.Cu as well as F.Cu, where In2.Cu carries signals. Its width is set against B.Cu, the nearest copper, which is not a plane |
SOLDERMASK_PAIRS_NEGOTIATE | off | 1: where a pair is left as routed, route the board again with the pair given room by every other net, and lay it there. Kept only where it lays more pairs and every net still connects |
SOLDERMASK_PLANES | gnd | A four-layer board's planes. gnd puts ground on In1.Cu and signals on In2.Cu. gnd+power puts the busiest power rail on In2.Cu instead |
SOLDERMASK_PRECEDENT_BAR | 0.6 | How similar a corpus board must be to seed the anneal |
SOLDERMASK_SES_CHECK | off | For debugging: 1 checks the copper walk against a full scan on every board, and stops on a difference |
SOLDERMASK_WIDEN_DEBUG | off | For debugging: set, a thin route's note says what held each track back from its width |
The cache
.cache/ holds downloads and generated files:
| Path | What it is |
|---|---|
parts/ | Catalogue answers, kept 24 hours |
jlcparts/ | The local copy of the JLCPCB catalogue |
jlcapi/ | Snapshots of JLCPCB's API catalogue, which setup --parts takes and writes jlcparts/ from |
params.db | The parametric index over the catalogue, which value parts resolve through |
easyeda/ | Footprints and symbols by LCSC code, kept until refreshed |
models3d/ | 3D models |
kicad-symbols/, symbol_index.json | The KiCad symbol library and its index (about 42 MB) |
datasheets/ | Datasheets, their text, and page images the reader showed a model |
components/ | Datasheet records the reader wrote, one per LCSC code. answers/ keeps every read's answer, so a record can be rebuilt without paying again. |
datasheet-warm/ | The warm-up tool's log: one line per part, with its cost |
krt/ | The A* router, when installed here |
vendor/ | The freerouting jar, for research tools only, when fetched here |
lan-cert.pem, lan-key.pem | The self-signed certificate |
access-token | The access token |
kicad-drc-config/ | An empty KiCad configuration that kicad-cli's DRC starts under, which is faster |
boards/ | The bank of open-hardware boards that precedents are drawn from, and placement annotations |
corpus/ | Every route the pipeline ran: the training data |
corpus-astar/ | The A* router's labels, which learn generate writes by default |
Deleting the cache
Downloads come back, but the corpus does not. It lives in .cache/corpus
and .cache/corpus-astar unless SOLDERMASK_CORPUS or
SOLDERMASK_CORPUS_ASTAR points elsewhere.
Clearing the cache also removes the symbol library, which three tests need.
Tooling
| Variable | What it sets |
|---|---|
SNAP_CHROME | The Chromium binary for tools/snap.py. Otherwise the Playwright cache is searched. |
PW_CORE, PW_CHROMIUM | playwright-core and its browser, for tests/verify_3d.js |
Routability
| Variable | Default | What it sets |
|---|---|---|
SOLDERMASK_ROUTABILITY | soldermask/assets/routability.json | The model that ranks placements. Point it at a soldermask learn train --out file to try one without shipping it. |
SOLDERMASK_CORPUS_ASTAR | .cache/corpus-astar | Where A* router labels are written |
SOLDERMASK_FREEROUTING_JAR | vendor/freerouting-2.4.1.jar in a checkout, .cache/vendor/ when installed | Research only: the freerouting jar that learn generate --router freerouting and the research tools run. No build uses it. |
SOLDERMASK_ANNOTATIONS | .cache/boards/annotations.jsonl | Placement annotations |
See Routability for the model.