Skip to content

Router that virtually distributes inference across connected devices in the home.

Go
6.6 KB
Raw Blame
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

import type { SupportedPlatform } from '@/shared/types/platform'

export type ModularProcessName =
    | 'nvpair-proxy'
    | 'broker'
    | 'node-info'
    | 'scanner'
    | 'manual-nodes'
    | 'node-settings'
    | 'engine-manager'
    | 'workload-manager'
    | 'cluster-manager'
    | 'errors'
    | 'job-scheduler'

export type ModularPackageArch = 'x64' | 'arm64'

/**
 * Who is responsible for spawning a modular binary at runtime:
 *
 * - `'broker'` — the binary is a worker the `nvpair-ui-broker` supervises. Electron
 *   passes its path to the broker (e.g. `--proxy-path`) but never spawns it
 *   directly. The broker owns its lifecycle, readiness, and log fan-out.
 * - `'electron'` — Electron's `ModularSupervisor` spawns the binary directly over
 *   stdio JSON-RPC. Only the broker itself is launched this way; it is then the
 *   parent of every broker-owned worker.
 *
 * As the broker absorbs more workers, flip the owner from `'electron'` to
 * `'broker'` and drop the direct spawn in `modular-supervisor.ts` — never run a
 * worker from both owners at once.
 */
type ModularLaunchOwner = 'broker' | 'electron'

interface ModularRuntimeBinary {
    processName: ModularProcessName
    baseName: string
    args: string[]
    launchOwner: ModularLaunchOwner
    needsFirewallAccess: boolean
    /**
     * When true, the supervisor skips spawning this binary if its file is
     * missing instead of throwing. Binaries are built from the sibling
     * `services/` tree (`build:modular-binaries`), so all sources are always
     * present; this flag only guards a missing/failed build of a non-critical
     * worker.
     */
    optional?: boolean
}

export const MODULAR_RUNTIME_BINARIES: ModularRuntimeBinary[] = [
    // Broker-owned workers. The broker spawns and supervises every one of these;
    // Electron only passes their resolved paths to the broker (see
    // `brokerStartupArgs` in modular-supervisor.ts) and never spawns them.
    {
        // One reverse-proxy process fronts every engine: the broker starts it
        // once and enables a facade per engine over `facade/enable`, so this
        // single entry is the whole proxy tier. Each facade binds its HTTP
        // listener on all interfaces, so it needs firewall access to be
        // reachable.
        //
        // Named for the binary, which is also the process: there is one, and
        // naming it after an engine would claim a per-engine process that does
        // not exist.
        // The per-engine identities are the relay sources (`ollama-proxy` /
        // `lmstudio-proxy`), which live in proxy-engines.ts.
        processName: 'nvpair-proxy',
        baseName: 'nvpair-proxy',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: true
    },
    {
        processName: 'scanner',
        baseName: 'nvpair-node-scanner',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: true
    },
    {
        processName: 'node-info',
        baseName: 'nvpair-node-info',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: true
    },
    {
        processName: 'workload-manager',
        baseName: 'nvpair-workload-manager',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: true,
        optional: true
    },
    {
        processName: 'cluster-manager',
        baseName: 'nvpair-cluster-manager',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: true,
        optional: true
    },
    {
        processName: 'node-settings',
        baseName: 'nvpair-node-settings',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: false
    },
    {
        // Client only: dials remote nodes' endpoints to probe manually added
        // hosts. It opens no network listener, so it needs no firewall access.
        processName: 'manual-nodes',
        baseName: 'nvpair-manual-nodes',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: false,
        optional: true
    },
    {
        // Serves its engine model list at `/v1/models` on all interfaces (the
        // broker starts it with `--http-port` so peers can enrich discovery from
        // it), so it needs firewall access.
        processName: 'engine-manager',
        baseName: 'nvpair-engine-manager',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: true,
        optional: true
    },
    {
        // The broker spawns nvpair-errors with `--peer-sync` itself, so PAIR UI
        // passes only the path (`--errors-path`).
        processName: 'errors',
        baseName: 'nvpair-errors',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: true,
        optional: true
    },
    {
        // Read-only routing policy: the broker fans it the discovery + workload
        // streams, and it emits `schedule:priority` which the broker fans out to
        // the proxies via `node/set-priority` (broker-internal — never surfaces
        // to the PAIR UI bridge). No network listener; stdio only.
        processName: 'job-scheduler',
        baseName: 'nvpair-job-scheduler',
        args: [],
        launchOwner: 'broker',
        needsFirewallAccess: false,
        optional: true
    },
    // Electron-direct: only the broker. Electron's ModularSupervisor spawns it
    // over stdio JSON-RPC, and it is then the parent of every worker above.
    {
        processName: 'broker',
        baseName: 'nvpair-ui-broker',
        args: [],
        launchOwner: 'electron',
        needsFirewallAccess: false
    }
]

/**
 * Binaries bundled in the installer but not spawned by Electron or the broker.
 * `nvpair-tui` is a headless terminal client that spawns its own `nvpair-ui-broker` —
 * see `services/nvpair-tui/README.md`.
 */
export const MODULAR_BUNDLED_BINARIES: { baseName: string }[] = [{ baseName: 'nvpair-tui' }]

/** Every backend binary shipped in the installer (runtime workers + bundled tools). */
export function modularShippedBinaryBaseNames(): string[] {
    return [
        ...MODULAR_RUNTIME_BINARIES.map(binary => binary.baseName),
        ...MODULAR_BUNDLED_BINARIES.map(binary => binary.baseName)
    ]
}

export function modularFirewallBinaryBaseNames(): string[] {
    return MODULAR_RUNTIME_BINARIES.filter(binary => binary.needsFirewallAccess).map(
        binary => binary.baseName
    )
}

export function modularBinaryFileName(baseName: string, platform: SupportedPlatform): string {
    return platform === 'win32' ? `${baseName}.exe` : baseName
}