Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* One-click "make this local runtime work" for the provider readiness checklist.
*
* `providerReadiness.js` answers WHAT is missing (the daemon isn't installed,
* isn't running, isn't serving the right model). Until this module existed, the
* answer to "so fix it" was a link — to the Models → Runtimes page for the two
* backends PortOS manages, and to the vendor's README for MTPLX, which is a
* dead end inside PortOS: the user leaves the app, reads a setup doc, runs two
* commands in a terminal, comes back and reloads. This module makes the
* checklist actionable in place: install the daemon, start it, and confirm the
* endpoint answers — from the button next to the failing check.
*
* Every command here comes from the fixed table below. A request names a
* runtime *kind* (`mtplx` / `llama` / `ollama` / `lmstudio` / `vllm` / `sglang`)
* and nothing else —
* no package, URL, port, or argument from the request ever reaches a shell
* word, which keeps this as narrow as `providerRuntimeInstaller.js`'s CLI
* install surface while removing the docs dead end.
*
* Three deliberate limits, because guessing here would be worse than a link:
*
* - **Weights are never downloaded behind a start.** llama.cpp cannot be
* started without a GGUF path the user chooses, and no runtime's *model*
* check is auto-fixed by a start — a multi-gigabyte download is a decision,
* and the Models → Runtimes page already owns that flow with a picker. `start`
* runs MTPLX on a checkpoint ALREADY in its cache (`lib/mtplxModels.js`).
* A cache that is empty (or holds only a half-finished pull) is a SEPARATE
* action the user clicks by name — `pull-start`, "Download the default
* model & start MTPLX" — never something a Start button does silently.
* Before that action existed the checklist offered only Start, which then
* failed with "no model weights are cached": the one fact that mattered was
* reachable only by clicking the button it made impossible.
* - **MTPLX's privileged paths are never touched.** Upstream ships an
* optional `mtplx max --install` fan-control helper behind a sudo prompt.
* PortOS installs the package and starts the loopback API server; that
* helper stays an explicit operator action outside PortOS, exactly as
* `docs/features/mtplx.md` promised before this button existed. Both of
* those steps are delegated to `mtplxServerManager.js`, so a server started
* here is the same PM2 process (`portos-mtplx`) the Models → Runtimes page can
* stop, log, and persist across a reboot — the two surfaces cannot drift
* onto different install commands or a daemon only one of them can see.
* - **Neither CUDA container is ever provisioned by a Start.** Both start rows
* bring up an already-prepared compose project and nothing else: no image
* build or pull, no weight download, no docker/WSL2/NVIDIA-toolkit install.
* A project that is not demonstrably prepared is refused — and, for vLLM
* since #4767, the checklist then offers the separate action that DOES
* provision it, "Clone, build & prepare … (~30 GB), then start", which is
* the same name-the-payload consent shape as MTPLX's `pull-start`.
* `install()` still refuses for both: Docker Desktop, the NVIDIA Container
* Toolkit and WSL2 are host-level operator decisions with driver
* requirements PortOS cannot judge, and that action provisions the PROJECT
* on a host already capable of running it. SGLang has no such action — it
* ships no provisioner of its own yet — and additionally refuses on a card
* the cookbook publishes no recipe for, BEFORE it would reach docker.
*/
import { LOCAL_RUNTIMES, localEndpointPort } from '../lib/localProviderRuntime.js';
import { expandPageToken } from '../lib/navManifest.js';
import { describeMtplxCache, listMtplxCachedModels } from '../lib/mtplxModels.js';
import { describeMtplxRuntime } from '../lib/mtplxRuntime.js';
import { listSlotstreamCachedModels } from '../lib/slotstreamModels.js';
import { probeOpenAiModels } from '../lib/openAiModelsProbe.js';
import { inspectSglangQwenProject, sglangStartBlockedReason } from '../lib/sglangQwenProject.js';
import { ensureSglangProjectDir } from './sglangQwenManager.js';
import { sglangUnsupportedReason } from '../lib/sglangQwenRecipe.js';
import { getCudaCapability } from '../lib/cudaCapability.js';
import { findCommandOnPath } from '../lib/processEnv.js';
import { runStreamingCommand } from '../lib/streamingSpawn.js';
import { installLlamaServer } from './llamaServerManager.js';
import { installMtplx, startMtplxServer, MTPLX_UNSUPPORTED_REASON } from './mtplxServerManager.js';
import { installSlotstream, startSlotstreamServer, SLOTSTREAM_UNSUPPORTED_REASON } from './slotstreamServerManager.js';
import { previewMtplxPull } from './mtplxModelManager.js';
import { assertDownloadFits } from '../lib/downloadPreflight.js';
import { controlOllamaServer, installBackend } from './localLlm.js';
import { isAppInstalled as isLmStudioAppInstalled } from './lmStudioManager.js';
import { provisionVllmQwenProject, readVllmQwenSetupState, startVllmQwenProject } from './vllmQwenManager.js';
/** A short command that only asks a running daemon to do something. */
const CONTROL_TIMEOUT_MS = 60 * 1000;
/**
* A model pull moves tens of gigabytes. Sized for a slow domestic line rather
* than for a fast one — a bound that kills a download at 90% is worse than no
* bound at all, and the user can close the modal to stop watching at any point.
*/
const WEIGHTS_TIMEOUT_MS = 6 * 60 * 60 * 1000;
/**
* Split a downloader's output on bare `\r` too, so a tqdm-style progress bar
* that redraws one line surfaces each redraw instead of buffering silently for
* the length of the download (`lib/streamLines.js`).
*/
const PROGRESS_SPLIT_RE = /[\r\n]+/;
/**
* How long a start step waits for a just-started daemon to answer. Sized for a
* cold multi-gigabyte model load, not for a socket coming up.
*/
const START_TIMEOUT_MS = 3 * 60 * 1000;
/**
* Bound on the `GET /v1/models` reachability probes. Loopback answers (or
* refuses) in single-digit milliseconds; the wider bound is for the FINAL
* confirmation, where a daemon that just finished loading a model can be slow
* to answer its first request and reporting it as down would be wrong.
*/
const PROBE_TIMEOUT_MS = 2_000;
const CONFIRM_TIMEOUT_MS = 5_000;
/**
* Why an installed MTPLX still cannot be started. Weights stay the user's
* decision (`docs/features/mtplx.md`), so a plain Start never fetches them —
* it names the button that does, plus the in-app card that searches for and
* downloads a checkpoint other than MTPLX's own default.
*/
const MTPLX_NO_MODEL_ERROR = expandPageToken('no model weights are cached, so its server exits before it binds a port. Close this window — the checklist now offers “Download the default model & start MTPLX”, which fetches MTPLX\'s own verified checkpoint (a multi-gigabyte download) and then starts the server. To use a different MTP checkpoint instead, search for one on the MTPLX card in {page}, download it there, then click Start MTPLX again.', LOCAL_RUNTIMES.mtplx);
/** The same dead end, reached from a cache holding only interrupted pulls. */
const mtplxPartialCacheError = (count) =>
expandPageToken(`its cache holds ${count} model${count === 1 ? '' : 's'}, but none passed its own file check — an interrupted download leaves a partial pack behind. Use “Download the default model & start MTPLX” on the checklist to re-fetch it, or pick another checkpoint on the MTPLX card in {page}.`, LOCAL_RUNTIMES.mtplx);
/**
* MTPLX's cache state, read WITHOUT invoking `mtplx`'s Homebrew wrapper before
* its Python runtime exists.
*
* `mtplx models --json` touches no network — but on a host where the wrapper
* has not bootstrapped its version-keyed venv yet, spawning it IS a
* several-hundred-megabyte pip install (`lib/mtplxRuntime.js`). The readiness
* checklist polls this, so without the gate a checklist refresh would kick off
* that download unannounced and then time out on it.
*
* A runtime that is not bootstrapped reports `unknown` — the cache genuinely
* could not be read, which is deliberately NOT `empty` — so the checklist does
* not claim MTPLX has no weights. A start attempted anyway is refused by
* `startMtplxServer` with `MTPLX_RUNTIME_NOT_BOOTSTRAPPED`, which names the
* download step rather than the checkpoint one.
*/
async function readMtplxCacheState() {
const runtime = await describeMtplxRuntime(findCommandOnPath('mtplx'));
if (!runtime.ready) {
return { state: 'unknown', model: null, count: 0, error: 'MTPLX\'s Python runtime has not been downloaded yet' };
}
return describeMtplxCache(await listMtplxCachedModels());
}
/**
* The `platforms` gate below is a static list, so its refusal has to be static
* too — read from the recipe module rather than re-typed, so the platform
* refusal and the runtime refusal cannot drift into telling an Apple Silicon
* operator two different things.
*/
const SGLANG_PLATFORM_UNSUPPORTED_REASON = sglangUnsupportedReason({ platform: 'darwin' });
/**
* The provisioning actions: the ones whose click IS the consent, because each
* spends bandwidth measured in gigabytes.
*
* A row owns at most ONE of them, declared as `row.provision = { action, run }`
* — and `describeRuntimeSetup` offers it only when that runtime's own offline
* read proves a plain Start cannot work. Everything
* needed to report the step lives in one entry so the button label and the
* progress lines cannot drift into describing different amounts of bandwidth.
*/
const PROVISION_STEPS = Object.freeze({
'pull-start': Object.freeze({
// Names the download so the click IS the consent.
label: (label) => `Download the default model & start ${label}`,
begun: (label) => `${label} is already installed — downloading its default checkpoint before starting it.`,
refused: (label) => `PortOS cannot download model weights for ${label}.`,
failed: (label, error) => `${label} model download failed: ${error}`,
done: (label) => `${label}'s default checkpoint is cached.`,
cancelled: 'Cancelled after the download — the weights are cached, but nothing was started.',
}),
'provision-start': Object.freeze({
// The payload named before the click: a ~9.5 GB image built on this host
// plus ~20 GB of weights. `install()` still refuses — this provisions the
// PROJECT on a host whose docker / NVIDIA / WSL2 setup is already the
// operator's own decision.
label: (label) => `Clone, build & prepare ${label} (~30 GB), then start`,
begun: (label) => `Docker is installed — preparing ${label}'s compose project before starting it.`,
refused: (label) => `PortOS cannot provision a compose project for ${label}.`,
failed: (label, error) => `${label} provisioning failed: ${error}`,
done: (label) => `${label}'s compose project is built and prepared.`,
cancelled: 'Cancelled after the prepare step — the project is ready, but nothing was started.',
}),
});
/**
* What each action actually DOES, and what it is called on the button.
*
* The capabilities are declared rather than spelled: `setupHint` used to ask
* whether an action name *contained* `install` or `start`, which worked only
* because every name happened to. `provision-start` broke the coincidence
* (it covers the download that `pull` used to stand for), and the next action
* named `bootstrap` or `prepare` would break it again — silently, since a
* missing hint fails no test. Declaring the three axes means a new action must
* answer them, and `describeRuntimeSetup` can hand the client `provisions`
* instead of the client re-deriving it from the name.
*/
const ACTION_CAPABILITIES = Object.freeze({
install: Object.freeze({ label: (label) => `Install ${label}`, installs: true, starts: false, provisions: false }),
start: Object.freeze({ label: (label) => `Start ${label}`, installs: false, starts: true, provisions: false }),
'install-start': Object.freeze({ label: (label) => `Install & start ${label}`, installs: true, starts: true, provisions: false }),
...Object.fromEntries(Object.entries(PROVISION_STEPS).map(([action, step]) => [
action,
Object.freeze({ label: step.label, installs: false, starts: true, provisions: true }),
])),
});
/** Every action `runLocalRuntimeSetup` accepts — route validation reads this. */
export const SETUP_ACTIONS = Object.freeze(Object.keys(ACTION_CAPABILITIES));
/**
* Does this action cover `installs` / `starts` / `provisions`?
*
* Exported so `providerReadiness.js` points each unmet check at the button that
* fixes it by asking THIS table, rather than matching substrings of the name.
*/
export const actionCovers = (action, capability) => ACTION_CAPABILITIES[action]?.[capability] === true;
/**
* The provisioning action a row owns, or `null` when it has no such step.
*
* A row declares BOTH halves or neither — there is no default. An implicit
* `pull-start` fallback would hand a new row "Download the default model &
* start X" and `X model download failed:` for a step that is not a download,
* which is the exact mislabeling PROVISION_STEPS exists to end.
*/
const rowProvisionAction = (row) => row?.provision?.action || null;
/**
* Fetch MTPLX's OWN default verified checkpoint — no repo id from the request,
* so this cannot be pointed at an arbitrary download. Runs only for the
* `pull-start` action, which the user clicks by its full name.
*/
async function pullMtplxDefaultCheckpoint({ emit, isCancelled }) {
const binary = findCommandOnPath('mtplx');
if (!binary) return { success: false, error: '`mtplx` was not found on PortOS\'s PATH. Restart PortOS so it picks up the new bin directory, then try again.' };
// Same disk-space guard the Models → Runtimes MTPLX card runs before its own
// pull — this readiness-checklist button reaches the same `mtplx pull`
// with no repo id, so it shares previewMtplxPull's cache path and its
// (unknown-size, so effectively best-effort) preflight. A refusal throws;
// the SSE route above already treats an unexpected throw from this step as
// a clean `{success:false}` termination, not a 500.
assertDownloadFits(await previewMtplxPull({}));
emit('Downloading MTPLX\'s default verified checkpoint. This is a multi-gigabyte download and can take a long while — leave this window open to watch it.');
// `mtplx pull` redraws one progress line with a bare `\r`; splitting on
// newlines alone would leave the stream silent for the whole download.
// `isCancelled` is load-bearing here, not decoration: this is the one step
// that can run for HOURS, and the route holds its single-setup lock until this
// promise settles. Without it, closing the modal leaves the download running
// and every other runtime's setup button refused for the rest of it.
return runStreamingCommand(binary, ['pull'], emit, { timeoutMs: WEIGHTS_TIMEOUT_MS, splitRe: PROGRESS_SPLIT_RE, isCancelled });
}
/**
* One row per local runtime PortOS can set up on its own.
*
* `platforms` is the HARD gate (an empty/absent list means every platform).
* `install` and `start` are async steps taking `({ emit, endpoint, isCancelled })`
* and returning `{ success, error?, note? }`; `start: null` means PortOS cannot
* start this runtime unattended and the checklist keeps its existing link.
*
* `provision: { action, run }` is the optional gigabyte-spending step: `action`
* names its PROVISION_STEPS entry (which supplies every string reported about
* it) and `run` takes `({ emit, isCancelled })`. Multi-step work belongs in a
* manager module — this table stays a table.
*/
const SETUP_ROWS = Object.freeze({
mtplx: Object.freeze({
platforms: ['darwin'],
unsupportedReason: MTPLX_UNSUPPORTED_REASON,
async install({ emit }) {
// Same install `mtplxServerManager` runs from the Models → Runtimes card:
// upstream's Homebrew tap, with pip as the documented fallback for a host
// without Homebrew. Neither runs the optional privileged fan-control helper.
const result = await installMtplx({ onProgress: (p) => { if (p?.message) emit(p.message); } })
.catch((err) => ({ success: false, error: err.message }));
return result;
},
/**
* What MTPLX's own cache holds, WITHOUT starting it — `mtplx models --json`
* is a local directory listing. Sits next to the `pull` step it gates so
* the two cannot drift, and `providerReadiness.js` reads it through
* `readRuntimeWeights` to put the same fact on the checklist.
*/
async weights() {
return (await readMtplxCacheState()).state;
},
provision: Object.freeze({
action: 'pull-start',
async run({ emit, isCancelled }) {
return pullMtplxDefaultCheckpoint({ emit, isCancelled });
},
}),
async start({ emit, endpoint, isCancelled }) {
// `mtplx serve` defaults `--model` to ONE hard-coded checkpoint and exits
// 1 before binding when that repo is not in its cache — even on a machine
// holding a different MTP model that would have served fine. Ask the
// cache first and name what is actually there. Read HERE rather than
// leaving it to the manager because the refusals differ by surface: this
// checklist can offer the `pull-start` download button, and the messages
// above say so; the Models → Runtimes launcher has no such button and names
// `mtplx pull` instead.
const cache = await readMtplxCacheState();
if (cache.state === 'unknown') {
// The cache could not be READ — which is not "read, and empty". Fall
// through to MTPLX's own default rather than blocking a start that may
// well work.
emit(`Could not read MTPLX's model cache (${cache.error}) — starting with its default model.`);
}
if (cache.state === 'empty') return { success: false, error: MTPLX_NO_MODEL_ERROR };
if (cache.state === 'partial') return { success: false, error: mtplxPartialCacheError(cache.count) };
// The manager emits "Serving the cached MTPLX model …" once it has the
// checkpoint, so don't announce it here too — both go to the same modal.
// The cache lookup is an awaited subprocess — the modal can close while it
// runs, and the caller's cancellation check happened BEFORE it. Without
// this, a cancelled setup still starts a server nobody asked to keep.
if (isCancelled()) return { success: false, error: 'Cancelled before the server was started.' };
// Delegated to the PM2-backed manager so a server started from this
// checklist is the SAME managed process the LLMs page can stop, log, and
// persist with `pm2 save` — a detached spawn here would be invisible there.
// The resolved checkpoint rides along so the manager does not walk the
// cache a second time for one start.
const port = Number(localEndpointPort(endpoint)) || undefined;
// This flow's contract is "the endpoint answers when the button finishes",
// so it buys the full cold-model-load budget rather than the launcher's
// short beat — MTPLX loads a multi-gigabyte MLX checkpoint before it binds.
return startMtplxServer({ port, model: cache.model, waitMs: START_TIMEOUT_MS, onProgress: emit })
.then(() => ({ success: true }))
.catch((err) => ({ success: false, error: err.message }));
},
}),
slotstream: Object.freeze({
platforms: ['darwin'],
unsupportedReason: SLOTSTREAM_UNSUPPORTED_REASON,
async install({ emit }) {
return installSlotstream({ onProgress: (p) => { if (p?.message) emit(p.message); } })
.catch((err) => ({ success: false, error: err.message }));
},
/**
* What Slotstream's cache holds, WITHOUT starting it — a local directory
* walk. There is deliberately no `provision` row beside it: PortOS does not
* fetch weights for this runtime, so the checklist reports an empty cache
* rather than offering a download button.
*
* This row is what keeps `standbyWhenStopped` honest. Without it
* `readRuntimeWeights('slotstream')` answers `'unknown'`, and a stopped
* Slotstream with an empty cache reads as "a valid idle state" — pointing
* the user at a start that cannot succeed.
*/
async weights() {
const cache = await listSlotstreamCachedModels();
if (cache.models === null) return 'unknown';
return cache.models.length > 0 ? 'ready' : 'empty';
},
async start({ emit, endpoint, isCancelled }) {
if (isCancelled()) return { success: false, error: 'Cancelled before the server was started.' };
const port = Number(localEndpointPort(endpoint)) || undefined;
return startSlotstreamServer({ port, waitMs: START_TIMEOUT_MS, onProgress: emit })
.then(() => ({ success: true }))
.catch((err) => ({ success: false, error: err.message }));
},
}),
vllm: Object.freeze({
// CUDA + Marlin + FlashInfer in a Linux container. On macOS there is no card
// to give it, and DFlash 2 on Apple Silicon is unproven in this project —
// the analogous local-daemon path there already ships as MTPLX / DSpark.
platforms: ['linux', 'win32'],
unsupportedReason: 'The vLLM Qwen3.8-27B stack needs an NVIDIA GPU (RTX 3090) and a Linux container runtime. On Apple Silicon use the MTPLX or llama.cpp DSpark presets instead.',
async install() {
// Deliberately never installs anything. Docker Desktop / the NVIDIA
// container toolkit / WSL2 are host-level operator decisions with driver
// requirements PortOS cannot judge, and the payload is a ~9.5 GB image.
return {
success: false,
error: 'PortOS does not install this stack. On the RTX 3090 host, set up WSL2 (or Linux) with Docker and the NVIDIA Container Toolkit — then the checklist can clone, build and prepare the compose project for you (see docs/features/qwen38-rtx3090.md).',
};
},
// What is on disk, in the checklist's four-state vocabulary — a directory
// read, exactly like MTPLX's cache read above. `'empty'` is what makes the
// checklist offer `provision-start`, and `vllmProjectSetupState` is careful
// to report it only where cloning/building/preparing IS the fix.
weights: readVllmQwenSetupState,
// This row's gigabyte-spending step is a compose provisioning run, not a
// model download — hence its own PROVISION_STEPS entry.
provision: Object.freeze({ action: 'provision-start', run: provisionVllmQwenProject }),
start: startVllmQwenProject,
}),
sglang: Object.freeze({
// Same posture as vLLM: CUDA in a Linux container. The hardware gate is
// narrower, though — the cookbook publishes single-GPU cells for Hopper and
// Blackwell only, and an Ampere 24 GB card keeps the vLLM stack (the SGLang
// cookbook has no 3090 cell). `sglangUnsupportedReason` reads the probe and
// says which of those it is, never collapsing a wedged `nvidia-smi` into
// "no GPU".
platforms: ['linux', 'win32'],
unsupportedReason: SGLANG_PLATFORM_UNSUPPORTED_REASON,
async install() {
// Deliberately never installs anything, for the same reasons as vLLM:
// Docker / the NVIDIA Container Toolkit / WSL2 are host-level operator
// decisions with driver requirements PortOS cannot judge.
return {
success: false,
error: 'PortOS does not install this stack. On the Hopper or Blackwell host, set up Docker with the NVIDIA Container Toolkit, then follow docs/features/sglang-qwen38.md — it carries the compose file (with the verified launch line) and the one-time weight download.',
};
},
async start({ emit, isCancelled }) {
// Refuse before docker on a card with no recipe, so a wrong-hardware host
// never reaches a `docker compose up` that would pull the image.
const cuda = await getCudaCapability().catch(() => null);
const unsupported = sglangUnsupportedReason({ status: cuda?.status, gpus: cuda?.gpus });
if (unsupported) return { success: false, error: unsupported };
// Before the inspection, because on a Windows host this is what decides
// WHICH directory gets inspected: the project is prepared by hand inside a
// WSL2 distro (Docker Desktop's engine IS that VM), and the default
// `%USERPROFILE%\sglang-qwen38` is a Windows path PortOS would find empty.
const misplaced = await ensureSglangProjectDir({ emit });
if (misplaced) return { success: false, error: misplaced };
// Only ever brings up an ALREADY-prepared project — see
// `lib/sglangQwenProject.js` for why each refusal exists.
const project = await inspectSglangQwenProject();
const blocked = sglangStartBlockedReason(project);
if (blocked) return { success: false, error: blocked };
if (isCancelled()) return { success: false, error: 'Cancelled before the container was started.' };
emit(`Starting the SGLang container from ${project.dir} (${project.composeFile}).`);
emit('The image and weights are already on disk — this only brings the service up.');
return runStreamingCommand(
'docker',
['compose', 'up', '-d'],
emit,
{ timeoutMs: CONTROL_TIMEOUT_MS, cwd: project.dir },
);
},
}),
ollama: Object.freeze({
async install({ emit }) {
// `installBackend` already registers the Homebrew service / runs the
// vendor script on Linux and starts the daemon afterwards, so it covers
// both steps for this runtime.
const result = await installBackend('ollama', (p) => { if (p?.message) emit(p.message); });
return result.success ? { success: true, note: result.note } : result;
},
async start({ emit }) {
emit('Starting the Ollama server…');
const result = await controlOllamaServer('start');
return result?.success ? { success: true } : { success: false, error: result?.error || 'Ollama did not start.' };
},
}),
lmstudio: Object.freeze({
async install({ emit }) {
const result = await installBackend('lmstudio', (p) => { if (p?.message) emit(p.message); });
return result.success ? { success: true, note: result.note } : result;
},
async start({ emit }) {
// `lms` is LM Studio's own CLI shim, installed by `lms bootstrap` from the
// app. Without it there is no headless way to start the server, and
// pretending otherwise would report a success the user cannot see.
if (!findCommandOnPath('lms')) {
return { success: false, error: 'LM Studio\'s `lms` CLI is not on PortOS\'s PATH. Open LM Studio once and run `lms bootstrap`, or start its local server from the app\'s Developer tab.' };
}
emit('Starting the LM Studio local server…');
return runStreamingCommand('lms', ['server', 'start'], emit, { timeoutMs: CONTROL_TIMEOUT_MS });
},
}),
llama: Object.freeze({
async install({ emit }) {
const result = await installLlamaServer({ onProgress: (p) => { if (p?.message) emit(p.message); } })
.catch((err) => ({ success: false, error: err.message }));
return result.success
? { success: true, note: expandPageToken('Choose a GGUF model on {page} to start llama-server — PortOS does not pick weights for you.', LOCAL_RUNTIMES.llama) }
: result;
},
// llama-server takes a required model path, and the weights are a separate
// multi-gigabyte download. Starting it unattended would mean guessing which
// checkpoint the user meant, so the Models → Runtimes page keeps that step.
start: null,
}),
});
/**
* What a runtime's own model cache holds, without starting it. `'unknown'` for
* every runtime with no cache PortOS can read offline — never `'empty'`, which
* would claim a fact PortOS does not have.
*
* Exported so `providerReadiness.js` reports the checklist from the SAME fact
* `describeRuntimeSetup` picks a button from; a second copy of the reader table
* over there is how the two would drift into disagreeing about one cache.
*
* @returns {Promise<'unknown'|'empty'|'partial'|'ready'>}
*/
export async function readRuntimeWeights(kind) {
const row = SETUP_ROWS[kind];
// A platform that cannot run the runtime discards this answer anyway
// (`describeRuntimeSetup` returns `blockedReason` and ignores `weights`), and
// the read is not free: vLLM's walks the compose project's candidate cache
// roots, which on the documented Windows shape is a dozen syscalls across a
// 9p share. Docker is on PATH almost everywhere, so without this gate a Mac
// would sweep for an RTX 3090 project once a minute, forever.
if (!row?.weights || !platformSupported(row)) return 'unknown';
return row.weights();
}
/** The cache states that make a start impossible. */
export const weightsBlockStart = (weights) => weights === 'empty' || weights === 'partial';
/** True when this host can run the runtime's setup at all. */
function platformSupported(row) {
return !row.platforms || row.platforms.includes(process.platform);
}
/**
* What (if anything) a "set this up for me" button should offer for one
* runtime, given what its readiness checks found. Pure — the client renders it
* straight from the readiness payload, so it must not probe anything.
*
* Returns `null` when there is nothing to offer: an unknown runtime, a platform
* that cannot run it, a runtime already installed and running (the remaining
* unmet check is the model, which PortOS will not choose), or a runtime PortOS
* can install but not start when the install is already done.
*
* `weights` is what the caller already learned about the runtime's local model
* cache (`lib/mtplxModels.js`'s `describeMtplxCache`), and only `'empty'` /
* `'partial'` change the answer: those are the states where a Start CANNOT
* work, so the button becomes the download that makes it possible instead of
* the start that is guaranteed to fail. `'unknown'` — the default, and what
* every runtime with no cache to read reports — deliberately keeps the old
* behavior; a cache PortOS could not read must not be treated as an empty one.
*
* @param {string} kind - `mtplx` | `llama` | `ollama` | `lmstudio` | `vllm` | `sglang`
* @param {{installed: boolean, running: boolean, weights?: 'unknown'|'empty'|'partial'|'ready'}} state
*/
export function describeRuntimeSetup(kind, { installed, running, weights = 'unknown' }) {
const row = SETUP_ROWS[kind];
const runtime = LOCAL_RUNTIMES[kind];
if (!row || !runtime) return null;
const needsInstall = !installed;
const needsStart = !running && Boolean(row.start);
if (!needsInstall && !needsStart) return null;
if (!platformSupported(row)) {
return { runtime: kind, label: runtime.label, action: null, actionLabel: null, provisions: false, blockedReason: row.unsupportedReason };
}
// Only offered once the binary is here: the cache cannot be read without it,
// so an uninstalled runtime's `weights` says nothing and `install-start`
// stays the honest first step.
const provision = rowProvisionAction(row);
const needsWeights = Boolean(provision) && !needsInstall && needsStart && weightsBlockStart(weights);
const action = needsWeights ? provision
: needsInstall && needsStart ? 'install-start'
: needsInstall ? 'install' : 'start';
return {
runtime: kind,
label: runtime.label,
action,
actionLabel: ACTION_CAPABILITIES[action].label(runtime.label),
// Whether this click spends gigabytes, answered HERE rather than re-derived
// from the action name in the client — a hand-kept mirror over there would
// silently downgrade the next provisioning button to an ordinary one.
provisions: actionCovers(action, 'provisions'),
blockedReason: null,
};
}
/**
* Install and/or start one local runtime, reporting progress line by line.
*
* Re-probes the endpoint first: the user may have started the daemon in a
* terminal since the page last polled, and re-running an install over a working
* setup is the one outcome a "fix it" button must not produce.
*
* Never throws — the caller is an SSE route whose headers are already flushed,
* so a failure has to come back as a value it can turn into a terminal frame.
*
* @param {string} kind
* @param {{endpoint: string, emit: (line: string) => void, isCancelled?: () => boolean, action?: string}} ctx
* `isCancelled` is checked between steps so a closed modal does not go on to
* start a daemon nobody is watching for. `action` is the one the checklist's
* button named; only a PROVISION_STEPS action adds a step (MTPLX's model
* download, vLLM's clone/build/prepare), and each is opt-in precisely so no
* other action can spend gigabytes of bandwidth. Omit
* it (`null`) and this resolves the action the checklist would offer right
* now — see the resolution comment below.
* @returns {Promise<{success: boolean, error?: string, message?: string}>}
*/
export async function runLocalRuntimeSetup(kind, { endpoint, emit = () => {}, isCancelled = () => false, action = null }) {
const row = SETUP_ROWS[kind];
const runtime = LOCAL_RUNTIMES[kind];
if (!row || !runtime) return { success: false, error: `PortOS has no automatic setup for \`${String(kind)}\`.` };
// The reachability probe comes BEFORE the platform gate on purpose: a daemon
// that is already answering is running whatever this host's platform is, and
// "MTPLX runs only on macOS" is a false report about a server the user can
// see working. The gate is about what PortOS may INSTALL, not about what is
// already up.
const target = endpoint || runtime.defaultBaseUrl;
const probe = await probeOpenAiModels(target, { timeoutMs: PROBE_TIMEOUT_MS });
if (probe.reachable) {
return { success: true, message: `${runtime.label} is already running at ${target} — nothing to do.` };
}
if (!platformSupported(row)) return { success: false, error: row.unsupportedReason };
const provision = rowProvisionAction(row);
// Refuse a step this runtime does not have BEFORE anything is installed. A
// `pull-start` aimed at Ollama would otherwise run Ollama's install on its way
// to being refused, and llama.cpp (`start: null`) would return the
// install-succeeded message without ever refusing at all. The mismatch check
// is by ACTION, not merely by "has a pull": vLLM owns `provision-start`, so a
// `pull-start` aimed at it is just as wrong as one aimed at Ollama.
if (actionCovers(action, 'provisions') && action !== provision) {
return { success: false, error: PROVISION_STEPS[action].refused(runtime.label) };
}
// Same two signals `providerReadiness.js` uses: the binary on PATH, plus LM
// Studio's macOS app bundle, which serves without ever putting `lms` there.
const installed = Boolean(runtime.command && findCommandOnPath(runtime.command)) ||
(kind === 'lmstudio' && isLmStudioAppInstalled());
// A request that names NO action came from a client built before `pull-start`
// existed — a stale `client/dist` (`pm2 restart` does not rebuild it) or a tab
// open across an upgrade. That client still renders THIS server's
// `setup.actionLabel`, so the user clicked a button reading “Download the
// default model & start MTPLX”; defaulting to a plain start would answer that
// click with the very "no model weights are cached" dead end this action
// exists to remove. Resolve what the checklist is offering instead, which is
// by construction the label they clicked.
// `installed &&` mirrors `describeRuntimeSetup`'s own gate: the cache cannot
// be read without the binary, so an uninstalled runtime never resolves to a
// download — and never spends a cache read to learn that.
const resolved = action || (provision && installed && weightsBlockStart(await row.weights()) ? provision : 'install-start');
if (!installed) {
const result = await row.install({ emit, endpoint: target, isCancelled });
if (!result.success) return { success: false, error: `${runtime.label} install failed: ${result.error}` };
emit(`${runtime.label} is installed.`);
if (result.note) emit(result.note);
} else {
// "already installed — starting it" was a lie whenever the click was a
// provisioning one: the next thing to happen is a clone or a multi-gigabyte
// download, and reporting a start makes every line after it read as a
// failure of the start. Each provisioning step says what it is about to do.
emit(resolved === provision
? PROVISION_STEPS[provision].begun(runtime.label)
: `${runtime.label} is already installed — starting it.`);
}
if (!row.start) {
return { success: true, message: expandPageToken(`${runtime.label} is installed. Pick a model on {page} to start it.`, runtime) };
}
if (isCancelled()) return { success: false, error: 'Cancelled after the install — nothing was started.' };
// The ONLY path that spends gigabytes, and it runs only because the user
// clicked a button that says so. `describeRuntimeSetup` offers it exactly
// when the runtime's own offline read is provably unusable, which is the
// state where a plain Start would exit before binding a port.
if (resolved === provision) {
const step = PROVISION_STEPS[provision];
const pulled = await row.provision.run({ emit, isCancelled });
if (!pulled.success) return { success: false, error: step.failed(runtime.label, pulled.error) };
emit(step.done(runtime.label));
if (isCancelled()) return { success: false, error: step.cancelled };
}
// The install step may have started it (Ollama's Homebrew service does), so
// re-probe rather than launching a second copy onto the same port.
const afterInstall = await probeOpenAiModels(target, { timeoutMs: PROBE_TIMEOUT_MS });
if (!afterInstall.reachable) {
const started = await row.start({ emit, endpoint: target, isCancelled });
if (!started.success) return { success: false, error: `${runtime.label} did not start: ${started.error}` };
}
const final = await probeOpenAiModels(target, { timeoutMs: CONFIRM_TIMEOUT_MS });
if (!final.reachable) {
return { success: false, error: `${runtime.label} was set up, but ${target} still does not answer${final.error ? ` (${final.error})` : ''}.` };
}
const served = Array.isArray(final.models) && final.models.length > 0
? ` It is serving ${final.models.slice(0, 3).join(', ')}${final.models.length > 3 ? ` +${final.models.length - 3} more` : ''}.`
: '';
return { success: true, message: `${runtime.label} is running at ${target}.${served}` };
}
/** The runtime kinds this module can set up — used by route validation and tests. */
export const SETUP_RUNTIME_KINDS = Object.freeze(Object.keys(SETUP_ROWS));