Skip to content

Command line and configuration

Command line

Command
python -m undine serve [--host 127.0.0.1] [--port 8700] [--llm-policy ...] [--mcp] [--import-root DIR] [--dep-root DIR] [--dep-host HOST] [--stop-jobs] start the server; --import-root (repeatable, default: home) limits where the UI may import GDS / OASIS from. --dep-root (repeatable, default: none) names the directories under which the browser and the HTTP API may add, update or sync a library dependency from a local repository (file://, /path, ~/path); without it they refuse every local one (the lib commands take any). --dep-host (repeatable) adds a remote host they may fetch a dependency or an index from; without it they fetch only from the hosts of the indexes this machine configures (the default index's, github.com, and those in $UNDINE_HOME/config.toml), and the lib and pkg commands fetch from any. A restart loses no work (Restarting the server): the simulations run on and the next server takes them up, unless --stop-jobs (stop them when this server stops)
python -m undine new PROJECT [--pdk sky130A] create a project pinned to a PDK (a bare name picks a version whose PCells Undine runs, the tested one first), with an undine.lock (created undine.lock (format 1))
python -m undine set-pdk PROJECT PDK pin a project to another PDK version, e.g. sky130A@8afc8346a57f (recorded in pdk_history and in undine.lock, which it creates when the project has none; to the version the project already has, it prints already ... and writes only a missing or other pin in undine.lock; see Moving a project to another PDK version). A format 2 lock stays format 2: it gets the new PDK's pin (full commit and tree hashes, read from the PDK, seconds for one not hashed before); to the PDK it pins already, the pin is kept as it is. Refused, with nothing changed, when a locked package does not accept the new PDK: error: the PDK ... is not accepted by N locked packages:, then a line per package with its chain and reason (exit code 1); a locked package neither in the store nor installed is refused with run lib sync first. To the PDK the project names already it is never refused
python -m undine import PROJECT LIB FILE (.gds or .oas) import a layout (the library is created when missing)
python -m undine pdk list (also pdks) list the PDKs found, with the full commit, where they came from (ciel, volare, - for a plain directory), the directory and the libraries installed (see Checking your PDKs)
python -m undine pdk verify PROJECT [--pin] [--network] hash the installed PDK (seconds the first time, then only the files whose stamp changed) and compare it with the pin in undine.lock; prints what differs, by part and file, then PDK <state> (verified, unverified, modified, missing, not pinned, other version); exit code 1 when the PDK is modified, missing or another version, or a locked library is not installed. Without --pin it never writes undine.lock. --pin pins the PDK as installed here (full commit, ciel source, libraries, a tree hash per part) and writes undine.lock as format 2, the other entries kept; on a format 2 lock it re-pins, and says what the old pin was. A locked package the new pin does not fit is a ! CHAIN: does not fit the PDK ... line, not a refusal (the exit code is the PDK's). --network: a 12-character id whose commit is not installed here may be looked up with ciel ls-remote. See Pinning the PDK
python -m undine pdk fetch PROJECT [--yes] [--network] install the project's PDK with ciel: prints the family, variant, commit, libraries, ciel source and the root it installs into, asks (--yes: does not ask; no answer, or not y: not fetched, exit code 1), runs ciel fetch, then compares the PDK with the lock. The root is the first PDK root scanned that ciel can install into; only ~/.volare is refused. A running server finds the PDK after Rescan PDKs (or POST /api/pdks/rescan). See Fetching a project's PDK
python -m undine pdk tested FAMILY [--all] the PDK commit of a ciel family (sky130, gf180mcu, ihp-sg13) that Undine is tested with, from its built-in profile; --all: every tested commit, one a line, the first the default. Exit code 1 for a family no built-in profile lists. ./setup.sh pdk reads it. Scans no PDK. See PDK profiles
python -m undine pdk enable FAMILY [COMMIT] ciel enable --pdk-family FAMILY COMMIT, COMMIT by default the tested one (pdk tested); prints the command, then ciel's output; the exit code is ciel's. With the global --pdk-root, ciel installs into the first of those roots it can install into, as for pdk fetch (ciel enable --pdk-root ROOT ...). pixi run pdk runs pdk enable sky130. Unlike pdk fetch it needs no project and does not compare anything with a lock
python -m undine store verify [--dry-run] re-hash every file and tree record of the store; removes those that do not match their name (--dry-run: says what it would remove) and makes a writable object read-only again; exit code 1 on any problem. Run lib sync in a project that used a removed one: it takes it again from its installed files, or fetches it
python -m undine store gc [--dry-run] remove the tree records and files of the store that no project here locks or installs: the projects under --root, the working copies of their changesets, and the projects elsewhere that ran a dependency command (the store keeps a list). Prints removed N tree records and M objects, <size> (would remove with --dry-run). A lock it cannot read stops it before it removes anything (nothing was removed: make these locks readable (or remove them), then run store gc again, exit code 1). Kept repositories, PDK records and compiled models stay
python -m undine doctor check the prerequisites (pixi run doctor)
python -m undine lib add PROJECT NAME GIT [--rev REV] [--subdir DIR] [--package P] add a library dependency, pinned in undine.lock: NAME: COMMIT12 (N cells), locked in undine.lock. A package prints NAME: P VERSION at COMMIT12 (N cells, M internal), locked in undine.lock, installed as NAME and P under another local name, + P VERSION as NAMES, via REQUIRER for each package it brought in, and ~ LABEL: WHAT (not trusted): a simulation using it needs python -m undine lib trust PROJECT NAME for each that holds what the trust rule refuses. --package P: the repository's manifest must name package P (written into project.json). Everything is checked first and refused at once, naming every problem (N problems with the dependencies: and a - line each), with nothing changed; a package with dependencies, or under another name, needs lock format 2 (needs lock format 2: run python -m undine lib lock PROJECT --format 2 first). A new name may not be a project or PDK library, devices, or a folder of Xschem's library or of symbol_paths
python -m undine lib update PROJECT NAME [--rev REV] move a dependency to another version (a package from an index: pkg update); prints the changed files and the cells using them, and for packages + P VERSION as NAMES (brought in), P: OLD @ C12 -> NEW @ C12 (moved), - P VERSION as NAMES: no longer needed. Takes the trust of what moved out of project.json. A name only a package places is refused: NAME: placed by X; update or remove that instead
python -m undine lib remove PROJECT NAME remove a dependency, with the packages nothing needs any more: removed P VERSION (installed as NAMES) or removed NAME (git C12) each; a package another dependency still places stays (NAME: still placed by X). Takes their trust out of project.json. A name only a package places is refused as for update
python -m undine lib trust PROJECT NAME [--untrust] [--yes] list what the trust rule finds in the dependency installed as NAME (NAME: P VERSION, trust key P@VERSION, then a line per finding: file, attribute, line, kind and text), then ask trust P@VERSION in PROJECT? [y/N] and add the key to project.json's trusted (P@VERSION: trusted in PROJECT (...)). --yes: does not ask. With no terminal and no --yes, or an answer other than y, nothing is trusted (exit code 1). --untrust: take the trust back, without asking. A dependency without a manifest has the key NAME@COMMIT12. Refused for a name not installed, or an install without a record (not installed by Undine: lib sync). No agent tool or undine call command reaches it
python -m undine lib sync PROJECT [--offline] install the dependencies exactly as locked, and remove any that project.json no longer names (its .undine/deps/<lib>/ and its undine.lock entry; printed as <lib>: removed <commit>); all or nothing: when one fails (a remote unreachable, files that do not match the lock), none is installed and none removed. Each package is installed under every local name the lock gives it; one the locked PDK does not fit is installed all the same, with a ~ CHAIN: does not fit the PDK ... line. Frozen: it resolves nothing, and refuses, before anything is read, a lock that does not pin a dependency as project.json names it (after a pull that changed project.json: run lib lock). A dependency in the store is installed from there, with no network. --offline (or UNDINE_OFFLINE=1) never fetches: what the store and the kept repositories lack is named and nothing is changed
python -m undine lib lock PROJECT [--format 2] lock what undine.lock does not pin as project.json names it (fetching and installing it, printed as <lib>: <commit> (sha ...), with , P VERSION for a package, and + P VERSION as NAMES, via REQUIRER for a package it brought in), and record the PDK and tool versions in use now. Also re-resolves an entry whose package's dependencies the lock does not install. --format 2 then writes the lock as format 2: the PDK pinned by its tree hashes (as pdk verify --pin), the tools with their origin, the entries as they are (each gets a tree the next time lib update or lib lock writes it); on a format 2 lock it leaves the PDK's pin alone. When what it resolves needs format 2 (a package's own dependencies, a package under another name), --format 2 converts the lock and resolves in one write, all or nothing: a refusal leaves the format 1 lock as it was; without --format 2 it is refused with that hint. A package the PDK it pins does not accept is a ! CHAIN: does not fit the PDK ... line, not a refusal
python -m undine lib status PROJECT what differs from undine.lock here: the PDK row (its state, as pdk verify names them), the dependencies, then ! issue, ~ warning and note: lines, and as locked when there is no issue. Exit code 1 on an issue only: a tool of another version or origin, another Undine version or a tools not pinned (pixi.lock not recorded) is a ~ warning, shown with the executable found here; the PDK unverified or unchecked, another Undine commit or another pixi.lock is a note. A dependency project.json no longer names but still installed or locked is leftover. One row per local name: a dependency's row ends with its package and version (-> P VERSION under another local name) and trusted or not trusted; a package another one brought in has via CHAIN on the next line, and the own-name row of a package added directly under another name has = NAME (the same install)
python -m undine pkg search [QUERY] [--index I] [--project P] the packages of an index whose name or description holds QUERY, one line each: NAME VERSION DESCRIPTION (LICENSE), the newest version that is not yanked. --index: a nickname or URL (default: the default index); --project: for the nicknames its project.json names. Exit code 1 when nothing matches
python -m undine pkg info PACKAGE [--index I] [--project P] what the newest version says (git, commit, tree, license, PDK, needs per dependency, exports) and every version listed, (yanked) marked
python -m undine pkg add PROJECT PACKAGE[@REQ] [--as NAME] [--index I] add a package from an index: the newest version that is not yanked, fits the PDK and that every requirement accepts, with the packages it needs; PACKAGE VERSION at COMMIT12 (N cells), requirement REQ, locked in undine.lock, then + P VERSION as NAMES, via REQUIRER per package it brought in. Without @REQ the requirement written to project.json is ^ the version taken. --as: another local name. Needs lock format 2; checked and refused as lib add is
python -m undine pkg update PROJECT [NAME ...] [--version REQ] fetch the index again and move each named package (default: every package from an index in project.json), with what only it reaches, to the newest version its requirement accepts: P: OLD -> NEW per package that moved, NAME: as locked when nothing did. --version: a new requirement for the one name, written to project.json
python -m undine pkg outdated PROJECT [--offline] each locked package from an index with a newer version: locked, the newest its requirement accepts (- for one only a package places), the newest listed, and direct or via who places it. Fetches each index first (--offline: reads the local copies)
python -m undine pkg tree PROJECT the dependencies as locked, as a tree ((*): shown above already)
python -m undine pkg why PROJECT PACKAGE every chain from the project to a locked package
python -m undine pkg lock PROJECT as lib lock
python -m undine pkg remove PROJECT NAME as lib remove
python -m undine pkg migrate PROJECT NAME [--index I] turn the git dependency NAME into a package from an index, when the index lists the version installed (its manifest's; the index's local copy is fetched again once when it does not) and that version's included files equal the installed ones, file by file: NAME: now P VERSION from URL, requirement =VERSION, then the files no longer installed (outside the manifest's [files] include). The requirement written is =VERSION; pkg update PROJECT NAME --version ^VERSION loosens it. A format 1 lock is converted to format 2 first, as lib lock --format 2. Refused, with nothing changed, for a dependency with no manifest, a version the index does not list, or a file that differs
python -m undine pkg sync PROJECT [--offline] [--from-vendor DIR] as lib sync. --from-vendor: first read the trees pkg vendor wrote into DIR (a tapeout bundle, or its vendor/) into the store, each directory hashed and compared with undine.lock before any file enters the store (NAME: imported from vendor/DIR, in store or not vendored), then install offline: no repository and no network. A vendored file changed, added or removed is refused, with nothing imported (Licences and vendoring)
python -m undine pkg licenses PROJECT [--json] the licence of every locked dependency (a package's from its manifest, else from the local copy of its index; a plain git dependency records none, and its top-level LICENSE, COPYING or NOTICE files are named) and of the PDK. Reads the store and the installs; fetches nothing. --json: LICENSES.json as pkg vendor writes it
python -m undine pkg vendor PROJECT DIR [--offline] [--yes] write DIR/vendor/: every locked tree as plain files (<package>@<version>/, a plain git dependency as <name>@<commit>/), vendor.json, LICENSES.json and LICENSES.md; DIR: N files, B bytes per tree. Each written tree is hashed again and compared with the lock before vendor/ is moved into place. A tree in neither the store nor the install is fetched after asking fetch them from their repositories? [y/N] (--yes: without asking; --offline: refused, nothing written). Refused when DIR/vendor/ exists. The PDK is recorded, not copied
python -m undine pkg index list [--project P] the indexes known here (undine, ~/.undine/config.toml's [indexes], project.json's indexes) with their URL and the commit last fetched
python -m undine pkg index update [NAME ...] [--project P] fetch indexes again (default: every one known): NAME: COMMIT12 each
python -m undine pkg index add NAME URL [--project P] give an index a nickname: NAME = "URL" into ~/.undine/config.toml's [indexes] (the rest of the file kept as written), or with --project into the project's project.json indexes, so that a clone finds it. Nothing changes when the name has that URL already; a name with another URL is refused
python -m undine pkg init LIBRARY [--name N] [--version V] [--license SPDX] [--repository URL] [--force] write LIBRARY/undine-package.toml for a library you publish. LIBRARY is the library's directory (its project found by walking up to project.json) or PROJECT/LIBRARY; a dependency's or a PDK's library is refused. Defaults: name the library's, version 0.1.0, exports the cells that have a symbol, the design's [files] include, [pdk] from the project's PDK (commits and built_with its full commit), the project's index dependencies the library's schematics place (^ the locked version), repository the git remote origin. A placed git dependency or project library is written as a comment. Prints each value it guessed (KEY VALUE (from where)) and ~ for what is missing (licence, repository, PDK commit). --license must be an SPDX expression (syntax only). An existing manifest is replaced only with --force
python -m undine pkg pack LIBRARY [--index I] [--check FILE --check-url URL] print the index line of the release: the package's subdirectory without uncommitted or untracked changes and HEAD at the tag v<version> (<name>-v<version> when the repository holds more than one package), else refused saying what to do. The tree is hashed from the local repository's blobs, as a consumer hashes it. A requirement from another index than --index (default: the default index) gets its URL. check is written only with both --check (its SHA-256) and --check-url (an https URL). A git dependency or a manifest without repository is refused
python -m undine pkg check LIBRARY --no-run [--index I] [--offline] [--out FILE] [--json] the checks of a publish that need no PDK, written to <project>/.undine/check/<name>-<version>/undine-check.json (--out: elsewhere; --json: printed too): the repository serves the tag at HEAD (--offline: not checked), file sizes (UNDINE_PKG_FILE_MAX) and LFS pointers, the licence, dependencies (no git ones; solved from the index, fetched first unless --offline), built_with equals the project's PDK commit, the libraries the schematics place, and the code blocks and RTL listed with what the trust rule refuses. Prints a summary, ~ per warning, ! CHECK: MESSAGE per problem and wrote FILE (sha256 HEX): passes or does not pass. DRC, LVS, the symbol and netlist checks and the specs are not run yet, so the report does not pass and the exit code is 1; without --no-run the command is refused for now. A package not clean at its tag is refused, with no report
python -m undine git-setup PROJECT make the project a git repository that diffs layout cells as text (Version control with git) and merges the files of a cell (.sch, .sym, .oas, .netlist.yaml, .intent.yaml) and the operation log object by object, and project.json and undine.lock entry by entry (semantic diff and merge), the merge bases of a criss-cross merge included (merge-driver --virtual-base), and installs a pre-commit hook that refuses unsaved layout edits (precommit; not over a hook of the repository's own, nor with core.hooksPath set: it then prints the command to add). Run it again to upgrade a project set up before, and in every clone; in a hook it installed, only the line that runs undine precommit is replaced, lines added to the hook stay; the lines of Undine's own output its .gitignore lacks (one added since, such as /changesets/requests/) are appended and named, the others kept. It commits nothing, and says when the repository has no commit yet (an applied changeset is committed only onto a branch with one: commit the project's files, or use Make the first commit in the History panel, whose Set up git makes that commit itself after its git init)
python -m undine textconv FILE.oas print a layout file as sorted text (the diff driver git-setup registers)
python -m undine merge-driver [--virtual-base] BASE OURS THEIRS PATH the merge driver git-setup registers (as python -P -m undine merge-driver %O %A %B %P; on Python 3.10, which has no -P, as python -c '<prelude>' merge-driver ..., the prelude taking the current directory off the module path: git runs it in the repository's top directory, whose files are never imported); git runs it for a file both branches changed. It writes the merged file into OURS, then a report into .git/undine-merge/PATH.json (local to the clone), and prints a line: what it merged, or the conflicts left open (a single one in its own words, which say what the file has for it) and the commands to go on with. Exit code 1 when conflicts are open (the file then has ours' value for each) or the merge failed (the file is then ours whole, the report has the error). With --virtual-base (registered as merge.undine-base.driver, which merge.undine.recursive names), the driver git runs to merge the several merge bases of a criss-cross merge into one: the merged file when they merge cleanly, else (a conflict open, or an error) their own base BASE whole (empty when they have none), so that the merge itself sees both branches' changes and stops on the conflict rather than taking one branch's resolution; exit code 0 either way, no report, a line only when it took the base
python -m undine resolve PATH [--theirs ID ...] [--ours ID ...] [--all-theirs] [--all-ours] merge a conflicted file again from git's index, taking the named side for those conflicts (--all-theirs / --all-ours: for every open one); decisions add up across runs. PATH is relative to the current directory or to the repository's top (as the driver prints it; :/PATH: from the top). git add :/PATH marks the file resolved. Exit code 1 while conflicts are open
python -m undine merge-check [DIR] [--commit C] [--json] in the project directory DIR (default: here), during a merge, cherry-pick or rebase, or for the merge commit C: the conflicts still open, the warnings, and the cells to verify with DRC / LVS (cells whose hierarchy is as neither branch had it). The warnings come from the driver's reports, which stay in the clone that merged: for a merge commit, the files it combined that have no report here are listed (their warnings are unknown). An octopus merge (git merge A B) takes every branch as a side and runs no driver: a committed one has no report, and while one is stopped at a conflict only the files resolve merged have one; merge-check says that such files were merged by lines. During a rebase or a cherry-pick of several commits it covers the commit git stopped at, and says so when earlier commits were applied (their warnings were printed when they were merged). After git merge --squash, git cherry-pick -n or git stash pop, which leave no commit for theirs, it shows the conflicted files with their conflicts and warnings, without the cells to verify. Exit code 1 while files are conflicted
python -m undine precommit the pre-commit hook git-setup installs: refuses the commit (exit code 1) when an operation log in the index (history/<lib>.jsonl as staged) holds layout edits not saved to the cell files, naming the library and the cells: save the layout in Undine and stage the files again, or commit with --no-verify to keep the journal (why). The commit that concludes a merge or a cherry-pick refuses only the unsaved edits made while concluding it (in neither branch's log): which of the branches' edits stay pending, the merge decided. That holds for git merge --squash (the other branch is the first commit SQUASH_MSG lists) and git cherry-pick -n too: journal records a merge copied here and not committed yet (merged_seq, not in HEAD's log) are never refused
python -m undine diff OLD NEW [--kind K] [--json] semantic diff of two files, with the merge's identities (the view from the file name, or --kind schematic, symbol, layout, netlist, intent, log)
python -m undine diff --rev A [B] [--dir DIR] [--json] semantic diff of every project file that changed from revision A to B (default: the working tree, with its untracked files that git does not ignore); layouts also show the XOR area per layer
python -m undine mcp-stdio [--url URL] [--ui-url URL] [--ssh HOST] [--no-start] [--no-open] local MCP entry for desktop AI apps: starts or reuses the server, opens the review (Agent and MCP); with --ssh, the server on HOST through an SSH port forward (Undine on another machine)
python -m undine mcpb [--out FILE] build the Claude Desktop extension (pixi run mcpb, into dist/)

Global options: --root DIR (projects root, default $UNDINE_ROOT or ~/undine-projects) and --pdk-root DIR (repeatable; replaces the default PDK roots $PDK_ROOT, ~/.ciel and ~/.volare, see Where Undine looks for PDKs).

The lib commands, pdk verify, pdk fetch and set-pdk read undine.lock before they change anything. One they cannot read is refused with one line (undine: ..., exit code 1), and project.json, undine.lock and .undine/deps/ stay as they were: a lock of a newer format (undine.lock has format 3, made by a newer Undine (this one reads formats 1 and 2) ...: update Undine), or one that is not valid JSON or has a format no Undine writes (fix it, or git checkout undine.lock). A lock without format is read as format 1. See troubleshooting.

Lock formats. Today's commands write format 1, and keep a format 2 lock format 2. Only two commands make a lock format 2: pdk verify PROJECT --pin and lib lock PROJECT --format 2 (undine.lock). A command that made undine.lock prints created undine.lock (format N). A package that names dependencies, or is added under a name other than its own, needs format 2: on a format 1 lock lib add, lib update and lib lock refuse it with needs lock format 2: run python -m undine lib lock PROJECT --format 2 first; nothing was changed.

Restarting the server

Restarting Undine (to deploy a change: ./scripts/restart.sh, Ctrl+C and start again, even kill -9) loses no work. Closing the server's terminal or SSH session (SIGHUP) stops it as Ctrl+C and SIGTERM do:

  • Running simulations go on. ngspice runs in a session (a process group) of its own, so it does not stop with the server (Ctrl+C in the server's terminal does not reach it either). The next server on the same projects root adopts each run whose ngspice still runs: it holds one of the UNDINE_SIM_JOBS slots, its time limit counts from its start, cancel_job stops it (with anything it started), and when it ends it is finished as any run (its log, raw file and measurements read; done or failed; whoever waits for it, e.g. wait_for job:<id>, is told). A run whose ngspice finished while no server ran is collected when it is next read. Adopting needs Linux (/proc); elsewhere a server's ngspice still ends with it when it stops (not after kill -9, which leaves it running with no server to collect it).
  • Queued simulations go on in their order (<root>/sim-queue.jsonl).
  • Calls in flight are not cut. When the server is asked to stop, a call that waits (wait_for, run_simulation's wait_s, check_specs, sweep, run_checks, extract_parasitics) answers at once with what it has (wait_for: "stopping": true, and a note that says whether the runs go on or were stopped with --stop-jobs; a DRC, LVS, extraction, RTL or LibreLane job it waited for ends with the server and is listed in ended), so the server stops within seconds; wait again afterwards, and run again what ended. run_checks and extract_parasitics answer "stopping": true too: their checks end with the server (and none starts while it stops), so call them again once the server is back.
  • A run no server can finish (its ngspice was killed or crashed, or the machine restarted) is interrupted, with why: run it again. So is a DRC, LVS, extraction, RTL or LibreLane run the stopped server left unfinished: only simulations are taken up. A server ends those runs as soon as it is asked to stop (they are interrupted at once, so the next server, which may already answer, runs such a check anew instead of reusing it), and starts no new one (it answers that the server is stopping: run it again once it is back). One killed outright (kill -9, a crash) cannot: the next server stops what is left of them as soon as it sees the run (its status records the tool's process), and cancel_job stops it too.
  • Agents keep their sessions. An MCP session goes on after the restart with the same changesets, the same write lock owner and its own jobs (<root>/mcp-sessions.json; a session unused for 30 days is forgotten); an agent the person stopped stays stopped. If the server does not know a session any more, the shell and Python clients start a new one and continue in it the changesets they had open. They, and mcp-stdio, send a call again while the server restarts (connection refused, or 503 from a proxy) for up to UNDINE_RESTART_WAIT_S (120 s), with the same request id, so a write is never done twice; over --ssh too (the forward accepts the connection and closes it: a call that can be sent twice waits while the server does not answer through it). An undine call made while it is down waits for it too, when its --session was with that server (a new session name says at once that Undine is not running). Agents sharing one --session (agent=NAME each) keep each other's changesets in the session file. A named --session is the agent of that name; one that opened its changeset before this version (unnamed) goes on with it under its name at its next call, its write lock handed over. This happens once: a changeset the session opens later with agent="" stays the unnamed agent's. After the first restart from an Undine before this version, the sessions whose simulations still run in a changeset are taken from those jobs, with that changeset open; another agent opens its changeset again (open_changeset id=...; a no job answer names the changeset that has the job).

One server at a time works on a projects root's simulations and keeps its sessions (it holds <root>/sim-jobs.lock): a second one started on the same root meanwhile (the next one while the last one still stops, or one too many) runs its own (listed in <root>/sim-queue-<id>.jsonl) and takes the others up once the first has gone; if the second one stops first, the first takes up what it left within seconds. A server stopping lets a run whose turn just came start first, so that the next one never starts it twice. A run started by an Undine before this version records no process: it is found by its directory and command line, and taken up once that server has gone (until then that server finishes it itself); the runs such a server had queued are interrupted.

To stop the simulations as well, start the server with --stop-jobs: when it stops, queued runs are cancelled and running ngspice processes are ended, with anything they started. A single run is stopped with cancel_job or Cancel in the simulation panel. A simulation left running while no server runs is not limited in time until a server takes it up again.

Configuration (environment)

Variable Default Used for
UNDINE_ROOT ~/undine-projects projects root (also read by the example scripts)
PDK_ROOT an extra PDK root, searched before ~/.ciel and ~/.volare; also where ciel installs (PDKs)
UNDINE_TOOLS the pixi environment under pixi run and in a server mcp-stdio starts from it; unset: the server's own environment (pixi, conda or venv), then ~/undine-tools prefix searched (bin/) for ngspice, Xschem, Netgen, Magic before PATH
UNDINE_PCELL_PYTHON .pixi/envs/pcell/bin/python Python that runs the sky130 and IHP PCell generators (gdsfactory 8.x with kfactory)
UNDINE_PCELL_GF180_PYTHON .pixi/envs/pcell-gf180/bin/python Python that runs the GF180MCU PCell generators (gdsfactory 7.9)
ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) the cloud agent
UNDINE_LLM_SERVER_URL / UNDINE_LLM_SERVER_KEY http://127.0.0.1:11434/v1 (Ollama) the EDA-server agent
UNDINE_LLM_POLICY both same as --llm-policy
UNDINE_MCP off same as --mcp
UNDINE_ENV, UNDINE_LOG, PORT ~/.undine/env, /tmp/undine.log, 8700 scripts/restart.sh: secrets file it loads, log file, port
UNDINE_AGENT_MAX_WRITES none an optional cap on the edits an agent may make in one changeset
UNDINE_SIM_JOBS the cores but two simulations (ngspice) the server runs at once; the others wait in order (queued, with their queue_position)
UNDINE_SIM_THREADS 1 ngspice threads (num_threads, OMP_NUM_THREADS) per simulation; 0 keeps ngspice's own setting (some builds set 8, which slows a shared machine down)
UNDINE_SIM_FULL_MODELS off 1: simulations read the PDK's whole model library, not a copy reduced to what the netlist uses (PDK models)
UNDINE_CACHE $XDG_CACHE_HOME/undine (~/.cache/undine) reduced model libraries (models/): made again when a library file changes, removed after 30 days unused. No longer used for the compiled Verilog-A models, which go to the store (build/, see UNDINE_STORE): models an earlier Undine compiled into osdi/<PDK id>/ here are still found until ./setup.sh osdi moves them into the store
UNDINE_SIM_TIMEOUT, UNDINE_SIM_TIMEOUT_MAX 3600, 43200 seconds a simulation may run unless the caller gives time_limit_s, and the most a caller may give; then ngspice is stopped
UNDINE_LIBRELANE librelane on PATH, else nix-shell ~/librelane --run how to run LibreLane: an executable, or a wrapper ending in --run (e.g. nix-shell /path/to/librelane --run)
UNDINE_HOME ~/.undine per-user files: connections added in the UI (connections.json, with their keys), the launcher's server log, the store
UNDINE_STORE $UNDINE_HOME/store the store alone: dependency files, kept git repositories, PDK hashes, compiled Verilog-A models (The store)
UNDINE_STORE_LINK link copy: dependencies are installed as read-only copies, not hard links into the store
UNDINE_OFFLINE off 1: lib sync and the sync of the HTTP API never fetch (as lib sync --offline)
UNDINE_CIEL the ciel beside Undine's Python, else PATH the ciel pdk fetch and pdk enable run (a path that is not a file: none runs)
UNDINE_FETCH_MAX 1073741824 (1 GiB) the most bytes the files of one dependency may have (and at most 100 000 files), and the most one fetch of a dependency or an index may receive
UNDINE_PKG_FILE_MAX 52428800 (50 MB) the most bytes one file of a package may have: pkg check reports a larger file as a problem
UNDINE_URL, UNDINE_UI_URL, UNDINE_OPEN http://127.0.0.1:8700, the server, the browser mcp-stdio: server to use or start, where the review opens, the command that opens it ({url} replaced)
UNDINE_SSH, UNDINE_MCP_TOKEN none, read from <projects root>/mcp-token mcp-stdio: the host Undine runs on (same as --ssh), the token to use instead of reading it
UNDINE_RESTART_WAIT_S 120 undine call, the Python client, mcp-stdio: how long a call refused while the server restarts (connection refused, 503 from a proxy) is sent again (Restarting the server)
UNDINE_CLI_SESSIONS ~/.undine/cli-sessions.json undine call, undine session: the file that keeps the shell's sessions (per server and --session name) between calls; agents side by side may each have one (Scripts and the shell)
UNDINE_MAX_CHARS 25000 undine call: the characters of a result it prints, shortened inside and still valid JSON (same as --max-chars; 0: all of it; Long results)