deployment installer

Installer

The public installer install.sh builds Prime Agent from the repository source into the current directory and links the prime-agent command globally. It is the quickstart path for end users and is different from the release-pipeline tarball flow, which ships prebuilt branded artifacts. This page describes the source installer and the checks that guard it.

Prerequisites

The installer verifies tooling before doing any work, in scripts/check-source-installer.mjs only in the sense that the shell script itself runs the checks inline. install.sh calls command_required for git, node, and npm, then runs node_is_supported which requires Node 22.8.0 or newer (major > 22, or 22 with minor > 8, or 22.8.x). It selects pnpm either from the system (pnpm_is_supported requires pnpm major 11) or falls back to an ephemeral npm exec --package pnpm@... install.

Environment overrides

install.sh reads three environment variables for testing or pinned installs:

• PRIME_AGENT_REPOSITORY_URL, the repository to clone (default https://github.com/Qredence/fleet-prime-agent.git).
• PRIME_AGENT_REPOSITORY_REF, the branch or tag to clone (default main).
• PRIME_AGENT_PNPM_VERSION, the ephemeral pnpm version when no system pnpm 11 is present (default 11.15.1).

Clone-or-reuse logic

install.sh does not always clone. prepare_checkout first calls checkout_matches_repository, which accepts the current directory when it is already a git checkout whose remote.origin.url matches the target repository (normalized to strip a trailing slash or .git, plus a small allowlist of the canonical Qredence URL forms). If it matches, the installer prints Using existing ... checkout and reuses it. Otherwise checkout_is_empty requires the directory to be empty; a non-empty, unrelated directory causes it to refuse with refusing to overwrite it. When it does clone, it runs git clone --branch <ref> --single-branch <url> ..

Build steps

build_checkout performs, in order:

1. npm ci --no-audit --no-fund to install the root npm workspace (packages/*).
2. pnpm install --dir web --frozen-lockfile to install the web/ pnpm workspace (via the selected system or ephemeral pnpm).
3. npm run build to build packages/tui, packages/ai, packages/agent, packages/coding-agent in order.
4. pnpm --dir web --filter @prime-agent/web build followed by node scripts/build-web-release.mjs to produce the packaged production web runtime under packages/coding-agent/dist/web.

link_cli then runs npm link ./packages/coding-agent, which makes the prime-agent bin from packages/coding-agent/package.json available on PATH. If the bin is not found after linking, it prints the global npm bin directory so the user can add it to PATH. The finished message tells the user to run prime-agent web from a project directory.

The web runtime

The source-built web runtime is what prime-agent web launches. scripts/build-web-release.mjs bundles the TanStack Start server into packages/coding-agent/dist/web/server, copies the client build to packages/coding-agent/dist/web/client, and copies the launcher to packages/coding-agent/dist/web/launcher.mjs. The web CLI command in packages/coding-agent/src/cli/web-command.ts spawns that launcher.

scripts/prime-agent-web-launcher.mjs is the launcher: it creates an HTTP server that serves the static client and proxies all other requests to the bundled web/server entry. It binds to 127.0.0.1:3000 by default and accepts --host and --port (and passes --cwd for the workspace root). It registers SIGINT and SIGTERM handlers to shut down cleanly.

Source-installer checks

The repo does not trust the installer by inspection alone. The check gate npm run check runs npm run check:installer and npm run check:browser-smoke:

• scripts/check-source-installer.mjs has two modes. --static (the check:installer target) runs sh -n for syntax and asserts the installer contains the required source-install steps (git clone, npm ci, --frozen-lockfile, npm run build, scripts/build-web-release.mjs, npm link ./packages/coding-agent) and does not contain release-only behavior (R2 URLs, install-beta.sh, global npm install -g). --smoke (the test:source-installer target) copies the working tree into a temp git mirror, runs the installer against it twice (once exercising the clone path, once the reuse path), verifies the global link and that the packaged web launcher starts and serves the root, health, and workspace-tree endpoints, and confirms the installer refuses an unrelated non-empty directory.
• scripts/check-web-release.mjs (npm run check:web:release) verifies the packaged release layout, recomputes the SHA256SUMS manifest, installs the packed tarball globally into a temp prefix, and smoke-tests the installed CLI's web command against a scratch workspace, asserting the root page, /api/health, /api/workspace/tree, and a served client asset.
• scripts/check-browser-smoke.mjs (the check:browser-smoke target) bundles scripts/browser-smoke-entry.ts for the browser with esbuild, marking @opentelemetry/api external, to prove the SDK graph builds for a browser target.

Related pages

• Deployment, the shipping model
• Getting started, install and run commands
• Release pipeline, the prebuilt tarball and npm release flow
• Build tools, the npm run check gate