Run local files through the CLI lab runner

This page runs one of your own source files on your own machine through the SynapseX lab runner. At the end you will have a script executing with its output streamed live and its exit code passed straight back to your shell — $0, off-ledger, no gate, and it works with no network connection.

Run a file


synapsex-code lab run <file> --local

Try it end to end. Save this as hello.py:


print("hello from lab local")

Then:


synapsex-code lab run hello.py --local

Observed output:


mode=local (off-ledger, $0)  file=hello.py
hello from lab local

The mode=local (off-ledger, $0) banner is the runner confirming what it did: your machine, nothing billed, no server involved.

Which interpreter runs my file?

The runner picks the interpreter from the file extension.

Extension	Runs with
`.py`	`python3` — override with the `SYNAPSEX_PYTHON` environment variable
`.js`, `.mjs`, `.cjs`, `.ts`	`node`
`.sh`, `.bash`	`sh`
`.rb`	`ruby`
`.pl`	`perl`
(no extension)	Executed directly — the file is assumed to have a shebang or be a binary

Any other extension is refused with an explicit unsupported-extension error naming the extension it did not recognise. Nothing is guessed.

To use a specific Python:


SYNAPSEX_PYTHON=python3.12 synapsex-code lab run hello.py --local

Behaviour you can script against

stdout and stderr are streamed live, not buffered until the end, so a long-running job shows progress as it happens.
The child’s exit code is propagated exactly. If your script exits 3, so does synapsex-code lab run.
A timeout produces exit code 124. The default timeout is 10 minutes.

That makes it safe to use as a normal step in a shell script or CI job:


if synapsex-code lab run analysis.py --local; then
  echo "analysis passed"
else
  code=$?
  [ "$code" -eq 124 ] && echo "analysis timed out after 10 minutes" >&2
  exit "$code"
fi

Why use this instead of just running the file?

Because the command shape does not change later. synapsex-code lab run <file> is the same entry point for local execution today and for remote compute when you move to it — you swap a flag, not the surrounding script. CI steps, Makefile targets and developer muscle memory carry over instead of being rewritten.

Today, two lab run modes need nothing but the installed binary: --local (this page) and --sim, the free offline quantum simulator.

What this does and does not protect you from

--local runs the file on your machine, with your user’s permissions, in the current directory. There is no sandbox and no isolation. Treat it exactly like typing python3 yourfile.py yourself: only run files you have read and trust.

What it does give you is honesty about cost and reach: this path never contacts the server, never uses a credential, and never spends anything.

Full flag list

Every lab flag: CLI commands.