Running in production
The app server is ready for production as it ships. There is no separate development mode to switch off.

What the server does
soldermask serve runs the app under Hypercorn.
| Area | What it does |
|---|---|
| Serving | TLS with a self-signed certificate for the LAN address, or your own behind a proxy. HTTP/2 and keep-alive. |
| Shutdown | Graceful. Every event stream gets a bye event, and shutdown takes about a second. |
| Builds | Run as jobs in a bounded thread pool (--workers, default 2). A request never waits on the model or the router. |
| Caching | The versioned static bundle is cached as immutable. Version files are cached for a day. Pages and API answers are no-store. |
| Compression | JSON and HTML are gzipped. |
| No third-party requests | three.js and the fonts are vendored, so the app works on a LAN with no internet. The standalone export uses CDNs, because it must be one file. |
| Hardening | A Content-Security-Policy with a nonce per request, HSTS on TLS, X-Content-Type-Options, X-Frame-Options and Referrer-Policy. |
| Limits | An 8 MB request body, a 20,000-character message, and a five-strike lockout on the login page. One route takes more: a project zip on POST /api/projects/import, up to 256 MB, from a client the access rule already lets in. |
| Access control | On by default. See Access control. |
| Observability | A timed access log (sync traffic left out), Server-Timing on every response, /api/health and /about. |
/api/health never touches git or the disk, so it is safe to poll.
/about shows the full picture, including whether the machine can build.
The one constraint
Run one server process per data directory. Jobs, the event bus and the per-project locks live in memory.
- Do not run two servers against the same
projects/. - Do not put a multi-worker WSGI server in front of it.
To scale, give each team or workspace its own directory and port.
Resources
A build places and routes the board. The first time a part is used, it also
fetches the part's footprint and 3D model. Under soldermask serve, the heavy
work runs outside the server's own process:
- The placer anneals its placements in worker processes, one per core.
- Lightcycle routes each whole board in a process of its own. A route still running after 600 seconds is stopped, and the gaps say so.
- A short board's retries under other settings are solved ahead in worker processes, one per core. The copper is the same as solving them in turn.
- On 32 cores or more, three placements are routed at once, each in its own process. Below that, they are routed one at a time.
--workers sets how many builds run at once. Each build reaches for every
core, so two builds at once share the machine. These settings cap one build:
| Setting | Default under serve | Sets |
|---|---|---|
SOLDERMASK_ANNEAL_WORKERS | One per core | Placements annealed at once |
SOLDERMASK_ROUTE_WORKERS | 3 on 32 cores or more, else 1 | Placements routed at once |
SOLDERMASK_ROUTER_RETRY_WORKERS | One per core | Retries of a short board solved at once |
SOLDERMASK_ROUTER_WALL_S | 600 | Seconds a whole-board route may run before it is stopped. 0 turns the limit off, and the route then runs in the build's own process. |
See Configuration for the rest.
The cache
The cache directory holds what a build fetched. Some of it is slow or costly to
fetch again. soldermask setup --check prints where the directory is.
| In the cache | If you delete it |
|---|---|
access-token | A new token is made. Every phone and script must log in again. |
lan-cert.pem, lan-key.pem | A new certificate is made. Each phone accepts the warning again. |
kicad-symbols/ | No pin is checked against a KiCad symbol until soldermask setup fetches them again. |
krt/ | The A* router is gone until soldermask setup --astar builds it again. |
jlcapi/, jlcparts/, params.db | The parts catalogue. A build fetches what it needs as it goes. soldermask setup --parts takes the whole catalogue again, which from JLCPCB's API takes over an hour. |
components/ | Records the datasheet reader wrote. Reading a sheet again is billed again. |
| Footprints, 3D models, parts lookups | Fetched again as builds need them. |
Run soldermask setup after clearing the cache.
Logs
Logs go to stderr, or to a file with --log-file PATH. An access line looks
like this:
2026-09-01 10:19:17 INFO hypercorn.access: 127.0.0.1:51817 "POST /api/projects/x/chat 2" 202 512 11342usJob starts, finishes and failures, with tracebacks, are logged under
soldermask.jobs.
Upgrading
- Pull the new code, or run
uv tool upgrade soldermaskfor a tool install. - From a checkout, run
pip install -e .andpip install ./mouldin the server's environment. - Run
soldermask setup. It reinstalls Lightcycle when the version this soldermask pins has changed. - Restart the server.
- Open
/about. Check it names the version you expect, whether it is tagged, and the Lightcycle version. - Optionally, run
soldermask projects rejudge. It judges every saved version's copper again with today's DRC, and rewrites the verdicts that change.--dry-runonly says what would change.
Projects written by an older layout are migrated the first time they are read.
A copy of the old project.json is left beside it. See
Projects on disk.