Quickstart

Requirements

• KLayout desktop build. Live workflows depend on the GUI macro environment and `pya`/`db` APIs.
• Python 3.10 or newer. The package metadata declares `requires-python = ">=3.10"`.
• Optional: Claude Code, Codex, or another MCP client.
• Optional per workflow: `gdsfactory`, the `klayout` Python package, NumPy/OpenCV, SciPy, scikit-learn, or scikit-image.

Supported versions

These versions are continuously verified by the public repo's CI gf-compat / klayout-compat matrices.

Install the Python package

python -m pip install klayout-klink

This installs `klink` and its own two Rust acceleration kernels, `klink-boxmaze-rs` and `klink-trackmaze-rs`. On unsupported platforms pip may build the kernels from source, which requires a Rust toolchain. For pure-Python core only:

python -m pip install klayout-klink --no-deps

Install optional feature dependencies only when needed:

python -m pip install klayout
python -m pip install gdsfactory
python -m pip install numpy opencv-python-headless
python -m pip install scipy scikit-learn scikit-image

Install the KLayout plugin

`klink_plugin` is a KLayout salt package. Copy the public repository or release checkout's `klink_plugin/` folder into KLayout's salt directory.

Windows PowerShell

cd path\to\klink
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\KLayout\salt" | Out-Null
Copy-Item -Path ".\klink_plugin" -Destination "$env:USERPROFILE\KLayout\salt\" -Recurse -Force

Linux / macOS

cd /path/to/klink
mkdir -p ~/.klayout/salt
cp -R klink_plugin ~/.klayout/salt/

Restart KLayout. A successful plugin startup prints something like:

[klink.server] listening on 127.0.0.1:8765

Smoke test

from klink import KLinkClient

with KLinkClient() as c:
    print(c.ping(nonce=42))
    print(c.layout_info(verbosity="summary"))

If KLayout is listening on a different port:

from klink import KLinkClient

with KLinkClient(port=8766) as c:
    print(c.ping())

Run the preflight check when in doubt:

python -m klink.doctor --port 8765

Your first result

Offline: EBL wraparound

PyPI-only users create a project first, then run the starter copied into the template:

klink init my-chip
cd my-chip
python example_template/nanodevice/ebl_wraparound.py

In a public source or release checkout, the gallery module path also works:

python -m examples_klink.public.demos.nanodevice.ebl_wraparound

Recorded public output summary: `"ok": true`, 40 electrodes, 12 patches, writefield 16 fields / 11 windows / 20 crossings, 0 violations, 0 overlaps.

Live KLayout: neural electrode harness

python example_template/nanodevice/neural_electrode.py --port <session-port> --elec-rows 4

Source or release checkout path:

python -m examples_klink.public.demos.nanodevice.neural_electrode --port <session-port> --elec-rows 4

Recorded public output summary: 48 ports, 24 routed nets, sibling-overlap 0, obstacle-hit 0.

Refresh starters after upgrading klink

After installing a newer klink, run `klink update` to refresh the starter demos under `example_template/`; your own files (`pdk.py`, `custom_devices/`, `.klink/`, `out/`, `specs/`) are never touched:

python -m pip install -U klayout-klink
klink update my-chip   # or run it from inside the project folder: klink update

Connect MCP

cd path\to\klink
klink-mcp --setup .

claude mcp add klayout -- python -m klink.mcp --profile read,write,verify,escape --session-id project-klink

Troubleshooting

• Python cannot connect: check KLayout is running, the plugin was copied, KLayout was restarted, and the port is correct.
• MCP tools exist but calls fail: MCP is running but KLayout is unreachable. Start KLayout and call `klink.reconnect` or restart the MCP client.
• gdsfactory tools miss dependencies: install `gdsfactory` into the same interpreter that runs the MCP server.
• PowerShell blocks venv activation: allow scripts for the current process.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1