~/.adom/adom-runtimes/

adom-bridge runtimes

# Managed runtimes: the Node and Python that Adom Bridge provides

Adom Bridge's bridges (the puppeteer browser bridge, the KiCad and Fusion 360
bridges, and any third-party bridge you install) are small Node.js or Python
programs. Instead of asking you to install Node or Python yourself, Adom Bridge
provisions both runtimes on its own and shares them across every bridge.

![The Runtimes panel in the Bridges sidebar](runtimes.png)

## Why Adom Bridge ships its own runtimes

- **Zero pollution of your machine.** If you already have Node or Python on
  your PATH, Adom Bridge simply uses it and downloads nothing. If you do not, Adom Bridge
  fetches a self-contained portable copy into its own folder. Nothing is
  registered system-wide, nothing lands in Program Files, and your own
  development setup is never touched.
- **No admin prompts, ever.** The portable runtimes are a plain zip extract
  (Node) and tar.gz extract (Python). There is no MSI, no installer, and no
  elevation, so you will never see a UAC dialog because of a runtime.
- **No firewall prompts by default.** Adom Bridge tells every bridge to bind
  `127.0.0.1` only (via the `ADOM_BIND_HOST` environment variable), so
  bridge servers listen on loopback and Windows Firewall stays quiet.

## Where they live

Portable copies are stored under:

```
~/.adom/adom-runtimes/
```

with one versioned folder per runtime. Current pinned versions are
Node 22.11.0 (from nodejs.org) and Python 3.12.13 (a full standalone CPython
build with venv and pip included).

## How to see their status

Two views of the same information:

- **The Runtimes panel** in the Bridges sidebar of the Adom Bridge window. Each
  runtime shows a state dot, its version, and its source: `system` means Adom Bridge
  is reusing an install already on your PATH, `adom-managed` means Adom Bridge
  downloaded the portable copy.
- **The CLI verb**, from any connected machine:

```bash
adom-bridge runtimes
```

It reports each runtime's state (`absent`, `installing`, `ready`, or
`failed`), source, and version, plus download progress while an install is
in flight.

## What gets downloaded, and when

- On every launch, about 3 seconds after boot, Adom Bridge prewarms both runtimes in
  the background (the `prewarm_runtimes` setting, on by default). If a
  system or previously cached runtime exists, this resolves instantly with
  no download. Only a machine with no usable runtime downloads the portable
  copy, once.
- If a bridge needs a runtime before the prewarm finishes, the bridge
  command returns a "warming" status instead of hanging; it succeeds on
  retry once the runtime is ready.
- Turning `prewarm_runtimes` off skips the background download; the runtime
  is then fetched lazily the first time a bridge actually needs it.

One detail worth knowing: the Windows Store ships a fake `python.exe` stub
that only offers to install Python. Adom Bridge detects and rejects that stub, so a
machine with only the stub gets the real portable Python instead of a broken
one.

## The guarantees

1. A runtime install never triggers a UAC elevation prompt.
2. Bridge processes bind loopback (`127.0.0.1`) by default, so no Windows
   Firewall dialogs.
3. Your own Node and Python installs are used when present and never
   modified.

For the developer-facing design and internals, see
`skills/MANAGED_RUNTIMES.md`; for the full launch-time background task
timeline, see `skills/PREWARM.md`.