service-kicad — shared headless KiCad

The shared service. service-kicad is a headless KiCad 10 service Adom runs as free shared infrastructure — DRC/ERC, Gerber/SVG/STEP export, Altium library conversion, and symbol/footprint/3D-model lookups with no local KiCad install. Every Adom tool and user container shells to the service-kicad CLI rather than hitting the HTTP API raw.

Fair use. It's free today and we intend to keep it that way. We reserve the right to rate-limit or block abusive usage, and if scale ever demands it, heavy usage may become paid. Nothing about your designs is retained beyond the job lifecycle.

Self-hosting. The service is a single container you can run yourself — full source on this page (Files tab / adom-wiki repo clone adom/service-kicad). If the shared instance doesn't fit, spin up your own and point the CLI at it. See Self-hosting below.

Install

adom-wiki pkg install adom/service-kicad

That installs the CLI to your PATH, the Claude skill, and bash completions. Verify:

service-kicad health

Usage

# Health / diagnostics
service-kicad health                  # service + KiCad version + running git_sha
service-kicad config                  # effective service URL and where it came from

# DRC / ERC
service-kicad pcb drc board.kicad_pcb
service-kicad sch erc schematic.kicad_sch

# PCB export
service-kicad pcb export gerbers board.kicad_pcb --out ./gerbers/
service-kicad pcb export step board.kicad_pcb --out board.step
service-kicad pcb export svg board.kicad_pcb --out board.svg
service-kicad pcb export svg board.kicad_pcb --layers F.Cu,F.Mask,Edge.Cuts --out board.svg

# Schematic export
service-kicad sch export svg schematic.kicad_sch --out sch.svg
service-kicad sch export svg-project ./project-dir --out ./sheets/   # hierarchical: one SVG per sheet
service-kicad sch export pdf schematic.kicad_sch --out sch.pdf
service-kicad sch export bom schematic.kicad_sch --out bom.csv

# Altium → KiCad library conversion
service-kicad altium sym part.SchLib      # → part.kicad_sym
service-kicad altium fp part.PcbLib       # → part.kicad_mod

# Symbol / footprint / 3D lookups (KiCad official libraries)
service-kicad sym svg Connector_Generic Conn_01x04
service-kicad fp svg Connector_PinHeader_2.54mm PinHeader_1x04_P2.54mm_Vertical
service-kicad model fetch Connector_PinHeader_2.54mm.3dshapes/PinHeader_1x04_P2.54mm_Vertical.step

3D models: STEP is the contract

For board 3D models, export STEP here and convert with adom-step2glb / service-occt — that is the only supported GLB path. KiCad-native GLB export is gated (page issue #106) because it bypasses the molecule pipeline: no MP-marker anchoring, no gold machine-pin material, no meter normalization, no footprint emit. The endpoints remain for legacy callers, but every GLB that leaves this service is provenance-stamped in its glTF JSON (asset.extras.adom.provenance = "kicad-native-glb", plus an X-Adom-Provenance response header) so importers and humans can catch it downstream, and the CLI verb requires an explicit --i-know-this-skips-the-pipeline acknowledgment.

The shared instance carries the official KiCad symbol/footprint/packages3D libraries only. Adom's machine-pin 3D libraries are not installed server-side, so molecule STEP export for boards using Adom library parts still runs on the laptop (see the kicad-export-molecule skill); boards built purely from the official libraries can use pcb export step here directly.

Service URLs — channels

Two channels run in parallel. The default URL serves KiCad 10; KiCad 9 is opt-in for callers that need to pin to the older toolchain.

The default URL is baked into the CLI. To pin a run to v9 (or any other instance):

SERVICE_KICAD_URL=https://kicad-v9-7f1gq8j5ohbq.adom.cloud service-kicad pcb drc board.kicad_pcb

(KICAD_SERVICE_API is honored as a legacy alias.) Health probe shape is the same on both channels; kicad_version and git_sha differ:

curl -sf https://kicad-rk5ue5pcfemi.adom.cloud/health
# → {"git_sha":"…","git_sha_short":"…","kicad_version":"10.0.2","ok":true,"service":"service-kicad","version":"1.1.0"}

Self-hosting

The whole service is one container: a Rust API binary shelling to kicad-cli, plus the official KiCad libraries. Everything you need is in this repo.

1. Provision a container. Follow the standalone service guide for creating a dedicated lightweight container with SSH. Any Ubuntu 24.04 host with ~10 GB free (KiCad + libraries) works too.
2. Get the source and deploy.

   adom-wiki repo clone adom/service-kicad && cd service-kicad
   bash deploy.sh
   

   deploy.sh is the canonical one-shot setup: installs KiCad 10 from the official PPA, overlays the upstream symbol/footprint/packages3D libraries (see library staleness below), builds the API, and installs the watchdog cron. Dockerfile documents the same steps as a reference image. KiCad 9 fallback: deploy-v9.sh on a separate host — the two PPAs ship the same kicad package, so it's one channel per host.
3. The watchdog keeps it running. watchdog.sh (cron, every 2 min) fetches origin, rebuilds on new commits, and health-checks the running service. It kills the old process by /proc/PID/exe readlink — not pkill -f path matching, which self-kills SSH sessions and can match unrelated processes. Keep that.
4. Expose the port. The API listens on PORT (default 8780). On an Adom container: adom-cli carbon containers port-add <slug> --port 8780 --prefix kicad. Health check: curl <url>/health — git_sha tells you exactly what's deployed.
5. Point the CLI at it.

   export SERVICE_KICAD_URL=https://your-instance.example
   service-kicad config   # confirms: source = SERVICE_KICAD_URL env
   

   Same commands, your container.

Service configuration

Uploads are capped at 100 MB per request.

Library staleness

The Ubuntu apt packages of kicad-symbols / kicad-footprints / kicad-packages3d lag the upstream KiCad GitHub repos by years (24.04 ships a ~2020 snapshot). Dockerfile + deploy.sh overlay shallow git clones of the upstream libraries at /opt/kicad-*-upstream, point the KICAD_*_DIR env vars at them, and refresh weekly via /etc/cron.d/kicad-lib-pull. The apt packages stay installed — they bring kicad-cli itself — but their library data is shadowed by the upstream clones.

HTTP API

Full contract: docs/service-kicad-api.md. Prefer the CLI over curling the API — it has the production URL baked in and insulates you from container reprovisions. Major endpoints:

Design doctrine

• Tool-agnostic by design. Zero aci-* deps — nothing in this repo imports adom-circuit. Bug fixes land once for every consumer.
• Body is the file. Every POST endpoint takes the raw .kicad_* bytes as the request body, not a multipart upload. Keeps clients trivial (curl --data-binary @file).
• Shell out; don't reimplement. kicad-cli is the source of truth. We're a thin HTTP layer over subprocess calls, not a KiCad reimpl.
• All exports pass KICAD{6,7,8,9,10}_3DMODEL_DIR so component 3D models resolve during STEP export, regardless of which kicad-cli major version is on the host.
• Static library mounts are read-only — nobody writes back through the service.
• $PORT configurable so the same binary can host side-by-side dev/prod instances on one container.

Contributing

Every change on main triggers the prod watchdog: on the next 2-minute cycle the container pulls, rebuilds, and relaunches — /health's git_sha confirms what's actually serving. Breaking changes bump api_version in service.json + docs/service-kicad-api.md. Open PRs against the wiki page (adom-wiki pr) so review happens where users look; the GitHub repo (adom-inc/service-kicad) is the working origin.