soldermaskdocs

Configuration

soldermask is set up with environment variables and a few flags on the serve command. There is no config file.

Where things live

VariableDefaultWhat it sets
SOLDERMASK_HOMEThe 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/projectsThe projects directory
SOLDERMASK_CACHE$SOLDERMASK_HOME/.cacheThe cache: parts, footprints, symbols, 3D models, the certificate and the access token
SOLDERMASK_CORPUS$SOLDERMASK_CACHE/corpusEvery route the pipeline runs, kept as training data
SOLDERMASK_DOCS<repo>/siteThe 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.

VariableDefaultWhat it sets
SOLDERMASK_BACKENDclaude-codeThe design model: claude-code, gemini, claude, groq or mercury. SILIXON_BACKEND is still read.
SOLDERMASK_CLAUDE_CODE_MODELclaude-fable-5-2The model the claude-code backend asks for
SOLDERMASK_CLAUDE_CODE_TIMEOUT_S900How long one claude-code turn may take, in seconds
GEMINI_API_KEY or GOOGLE_API_KEYnoneGemini credentials
ANTHROPIC_API_KEYnoneCredentials for the claude backend. A logged-in ant auth profile also works.
GROQ_API_KEYnoneGroq credentials
GROQ_MAX_OUTPUT_TOKENS16000The most output tokens one Groq call asks for
INCEPTION_API_KEYnoneCredentials for the mercury backend
TYPESAFE_API_KEYnoneJev'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_S600How long one Gemini call may take, in seconds
SOLDERMASK_AUTO_REPAIR1Rounds of revision for a chat turn whose build fails its checks. 0 turns it off.
SOLDERMASK_MODEL_CALLSonnone (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.

VariableDefaultWhat it sets
SOLDERMASK_DATASHEET_READERoffazure turns the reader on, for read_datasheet and soldermask parts read only. A build never runs it on its own.
SOLDERMASK_READER_MAX_USD0.50The 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_DRAWoffon 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_KEYnoneThe Azure key. It may also sit in .env under the home directory. Without one, the reader asks the az command line.
SOLDERMASK_READER_AZURE_RESOURCEsoldermask-astra/soldermask-astra-e2The resource group and account az reads the key from
SOLDERMASK_READER_ENDPOINT or AZURE_AI_ENDPOINThttps://soldermask-astra-e2.cognitiveservices.azure.comWhere 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 flagWhat it sets
SOLDERMASK_TOKENThe access token. off, none or 0 turns access control off, like --no-auth.
--token, --no-auth, --proxy, --workers, --log-file, --http, --port, --hostSee Command line
SOLDERMASK_MCP_KEYS, SOLDERMASK_MCP_PROJECTS, SOLDERMASK_MCP_BUILDSThe MCP server over HTTP. See MCP server.
SOLDERMASK_MCP_LOGA file the MCP server appends one JSON line a tool call to, over stdio or HTTP. Unset, nothing is logged.

Services

VariableDefaultWhat it sets
JLCPCB_APP_ID, JLCPCB_ACCESSKEY, JLCPCB_SECRETKEYnoneJLCPCB API credentials, for the catalogue, stock and price from JLCPCB itself. soldermask setup --check says whether the app is granted the Parts API.
JLCPCB_ENDPOINThttps://open.jlcpcb.comWhere JLCPCB's API is served
GH_TOKEN or GITHUB_TOKENnoneA GitHub token soldermask setup downloads Lightcycle with, when the gh command is not signed in

The terminal

VariableWhat it sets
NO_COLORTurns colour off, and with it the board's picture
FORCE_COLORTurns colour on, even into a pipe
COLORTERMtruecolor or 24bit gives the 24-bit orange; otherwise the nearest of 256 colours
TERMdumb turns colour off

Building

VariableDefaultWhat it sets
SOLDERMASK_ROUTERlightcycleThe first router for a design that names none: lightcycle or krt (the A* router). A design's own rules.router wins.
SOLDERMASK_ANNEAL_WORKERSOne a core under the CLI, the app, soldermask mcp --http and soldermask.evaluate; 1 in the library and the stdio MCP serverPlacements annealed at once
SOLDERMASK_ROUTE_WORKERS3 on 32 cores or more, else 1Placements routed at once
SOLDERMASK_ROUTE_PROCESSESonPlacements 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_NICE10How far down raced placements after the first run, so they use spare cores only. 0 runs them all at one priority
SOLDERMASK_ROUTER_RETRY_WORKERSOne a core under the CLI, the app, soldermask mcp --http and soldermask.evaluate; 1 in the library and the stdio MCP serverLightcycle retries of a short board solved at once. The copper is the same; it takes more CPU
SOLDERMASK_ROUTER_WALL_S600Seconds 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_ANNEALautoThe anneal loop: auto (compiled when built), python, or rust (an error if not built)
SOLDERMASK_MOULDautoThe mould's loop: auto, or numpy to force the reference
SOLDERMASK_MOULD_THREADS0 (all)Threads for the compiled mould
SOLDERMASK_SPACING_MM0.5Air between parts, in mm. 0 packs courtyards together; auto works it out from the board's room.
SOLDERMASK_PRECEDENT10 stops a corpus board seeding the anneal
SOLDERMASK_SIMon0 skips the simulation stage
SOLDERMASK_NGSPICEngspice on PATHThe ngspice program, or libngspice
SOLDERMASK_OFFLINEoff1 stops every network call. A cache miss is then a miss.
SOLDERMASK_PARTSjlcpartsjlcsearch 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/pythonThe A* router's checkout and its Python

Experiment switches

These change the pipeline for a measurement. The defaults are what ships.

VariableDefaultWhat it changes
SOLDERMASK_MOVES_PER_PART8000Anneal moves per free part. 0 gives the old fixed 20,000 steps.
SOLDERMASK_ROT3601A turn picks 90, 180 or 270 degrees. 0 keeps every part at 0 or 90.
SOLDERMASK_SWAP_P0.1How often the anneal swaps two parts. 0 turns swaps off.
SOLDERMASK_ANTENNA_KEEPOUT10 stops the placer charging for parts under a module's antenna
SOLDERMASK_ESD_W4Weight pulling ESD parts to the connector they guard; 0 turns it off
SOLDERMASK_PADACCESS_W0 (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_CLAIM1On 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_SHARED1The 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_UNSTARVE1A 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_VIAS1When 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_CHECKon0 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_RULES10 stops the build checking datasheet layout rules. They are advice and never change the verdict. See Datasheet layout rules.
SOLDERMASK_LAYOUT_RULES_FILEsoldermask/assets/layout_rules.jsonAnother rules file to check against. A missing file checks nothing.
SOLDERMASK_SIZE_TARGET0.45The 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_MM0 (off)A ring of room around fine-pitch parts, in mm
SOLDERMASK_POWER_POURunset1 pours the power nets the pipeline picks, 0 pours none, or a comma-separated list of nets
SOLDERMASK_POWER_FALLBACKonA board whose copper alone fails is built again with its power nets poured, and the better build is kept. 0 builds once
SOLDERMASK_POWER_SHAPEunsetA power pour's outline: hull, tree or mould
SOLDERMASK_GROUND_FIRSToff1 gives every surface ground pad a via before signals route
SOLDERMASK_DECAP_SITESoff1 gives each decoupling capacitor's ground pad, and its chip's ground pins, a via before signals route
SOLDERMASK_SIGNALS_FIRSTswapWhere 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_ESCAPEonLays 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_COPPERonThe 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_PARALLEL10 runs the pour's fallback route after the main one, not beside it
SOLDERMASK_POUR_EP_SITES1A 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_FANOUToffstub or underpad escapes fine-pitch pads before the A* router
SOLDERMASK_TANDEM10 stops Lightcycle routing every placement to rank them
SOLDERMASK_TANDEM_MORE3Fresh placements annealed and routed when none of the first reaches every pin. 0 adds none
SOLDERMASK_ROUTER_RETRYon0 stops a short board's retries after the finer grid, so the three other settings are not tried
SOLDERMASK_ROUTER_RETRY_SHORT2The other settings are tried only on a board this many pins short or fewer
SOLDERMASK_ROUTER_RETRY_GRID_SHORT6The 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_KEEPoff1 also tries the finer grid on the pour's re-route around copper it keeps
SOLDERMASK_ROUTER_NECK_MM1.0How 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_THREADS1Lightcycle threads for nets that do not meet
SOLDERMASK_ROUTER_PRES00.6The congestion price Lightcycle starts at. Higher ends in fewer rounds and more vias
SOLDERMASK_ROUTER_PRES_GROW1.4How much that price grows each round
SOLDERMASK_ROUTER_BRANCHES10 makes Lightcycle reroute whole nets
SOLDERMASK_LC_EXACToff1 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_THIN0.5,0Width caps for a short board's thin route, in mm; 0 is the board's track; empty turns it off
SOLDERMASK_ROUTER_THIN_RANK10 keeps the thin route out of the pass that ranks placements; faster, and it closed fewer motor boards
SOLDERMASK_ROUTER_POWER_FIRST01 routes a short board's wide nets alone first, then the rest round them; experimental
SOLDERMASK_ROUTER_POWER_FIRST_MM0.5With SOLDERMASK_ROUTER_POWER_FIRST=1, the nets wider than this, in mm, are routed first
SOLDERMASK_ROUTER_UPGRADE12How many warm nets of a thin route are routed again alone, wider
SOLDERMASK_WIDEN_SHOULDERS10 widens a thin route's tracks about their centre only
SOLDERMASK_WARM_C20A narrow run this many °C over the room is a gap
SOLDERMASK_HOT_C100A narrow run this many °C over the room fails the verdict
SOLDERMASK_PAIRS10 routes a differential pair's two nets as two nets, not side by side
SOLDERMASK_PAIRS_IN201 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_NEGOTIATEoff1: 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_PLANESgndA 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_BAR0.6How similar a corpus board must be to seed the anneal
SOLDERMASK_SES_CHECKoffFor debugging: 1 checks the copper walk against a full scan on every board, and stops on a difference
SOLDERMASK_WIDEN_DEBUGoffFor debugging: set, a thin route's note says what held each track back from its width

The cache

.cache/ holds downloads and generated files:

PathWhat 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.dbThe 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.jsonThe 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.pemThe self-signed certificate
access-tokenThe 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

VariableWhat it sets
SNAP_CHROMEThe Chromium binary for tools/snap.py. Otherwise the Playwright cache is searched.
PW_CORE, PW_CHROMIUMplaywright-core and its browser, for tests/verify_3d.js

Routability

VariableDefaultWhat it sets
SOLDERMASK_ROUTABILITYsoldermask/assets/routability.jsonThe model that ranks placements. Point it at a soldermask learn train --out file to try one without shipping it.
SOLDERMASK_CORPUS_ASTAR.cache/corpus-astarWhere A* router labels are written
SOLDERMASK_FREEROUTING_JARvendor/freerouting-2.4.1.jar in a checkout, .cache/vendor/ when installedResearch only: the freerouting jar that learn generate --router freerouting and the research tools run. No build uses it.
SOLDERMASK_ANNOTATIONS.cache/boards/annotations.jsonlPlacement annotations

See Routability for the model.

On this page