@forgezero/agent 0.1.35 → 0.1.36

package/dist/fz.js

@@ -4875,7 +4875,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION2 = "0.1.35";
+var VERSION2 = "0.1.36";
 
 // src/software.ts
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
@@ -4889,7 +4889,8 @@ var SOFTWARE_CATALOG = [
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
-  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
   {
@@ -4916,6 +4917,11 @@ var UBUNTU_2604_X64 = [
     requirement: { id: "ufw", version: "ubuntu-26.04" },
     check: "command -v ufw >/dev/null",
     install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
+  },
+  {
+    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
+    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
   }
 ];
 function validateSoftwareRequirements(value, _options = {}) {
@@ -4929,7 +4935,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };
@@ -5482,7 +5488,12 @@ function agentUnit(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
+  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapTargetTelemetryEndpoint);
+  if ([options.pullBootstrap, options.bootstrapSshCredentialPath, options.bootstrapTargetTelemetryEndpoint].some(Boolean) && !bootstrapEnabled) {
+    throw new Error("bootstrap pull, SSH credential and target telemetry endpoint must be supplied together");
+  }
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
+  const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
   const warpValues = [
     options.warpOrganization,
     options.warpClientIdCredentialPath,
@@ -5548,6 +5559,9 @@ function agentUnit(options) {
     options.publicApiUrl ? `FZ_PUBLIC_API_URL=${options.publicApiUrl}` : null,
     options.pullDeployments ? "FZ_DEPLOY_PULL=true" : null,
     options.pullMigrations ? "FZ_MIGRATION_PULL=true" : null,
+    options.pullBootstrap ? "FZ_BOOTSTRAP_PULL=true" : null,
+    options.pullBootstrap ? "FZ_BOOTSTRAP_SSH_KEY_CREDENTIAL=bootstrap-ssh-key" : null,
+    options.pullBootstrap ? `FZ_BOOTSTRAP_TARGET_OTLP_ENDPOINT=${options.bootstrapTargetTelemetryEndpoint}` : null,
     `FZ_AGENT_UPDATE_SOCKET=${DEFAULT_AGENT_UPDATE_SOCKET}`,
     options.pullMigrations ? `FZ_LIFECYCLE_HELPER_SOCKET=${lifecycleHelperSocketPath}` : null
   ].filter((line) => line !== null);
@@ -5555,6 +5569,8 @@ function agentUnit(options) {
     environment.push(`HOME=${deployRoot}/agent-home`, `XDG_CACHE_HOME=${deployRoot}/cache`);
   }
   const gitCredential = options.gitCredentialPath ? `LoadCredentialEncrypted=git-deploy-key:${options.gitCredentialPath}
+` : "";
+  const bootstrapCredential = bootstrapEnabled ? `LoadCredentialEncrypted=bootstrap-ssh-key:${bootstrapSshCredentialPath}
 ` : "";
   const projectCredentials = Object.entries(deploymentCredentials).map(([name, path]) => `LoadCredentialEncrypted=${name}:${path}`).join(`
 `);
@@ -5609,7 +5625,7 @@ User=${user}
 Group=${VAULT_GROUP}
 ${deploymentGroup}
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
-${gitCredential}${projectCredentials}${projectCredentials ? `
+${gitCredential}${bootstrapCredential}${projectCredentials}${projectCredentials ? `
 ` : ""}${snpPrepare}ExecStart=${bin}
 Restart=always
 RestartSec=2
@@ -5664,6 +5680,10 @@ function planProvision(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
+  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapTargetTelemetryEndpoint);
+  if ([options.pullBootstrap, options.bootstrapSshCredentialPath, options.bootstrapTargetTelemetryEndpoint].some(Boolean) && !bootstrapEnabled) {
+    throw new Error("bootstrap pull, SSH credential and target telemetry endpoint must be supplied together");
+  }
   const warpValues = [
     options.warpOrganization,
     options.warpClientIdCredentialPath,
@@ -5689,13 +5709,20 @@ function planProvision(options) {
   const gitPublicKeyDir = gitPublicKeyPath?.replace(/\/[^/]+$/, "");
   const lifecycleProfilePath = lifecycleEnabled ? systemdPath(options.lifecycleProfilePath, "lifecycle profile") : undefined;
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
+  const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
   const warpClientIdCredentialPath = warpEnabled ? systemdPath(options.warpClientIdCredentialPath, "WARP client-id credential") : undefined;
   const warpClientSecretCredentialPath = warpEnabled ? systemdPath(options.warpClientSecretCredentialPath, "WARP client-secret credential") : undefined;
   return {
     mode,
     reason: reasonFor(mode),
     unitPath: UNIT_PATH,
-    unit: agentUnit({ ...options, mode, lifecycleProfilePath, lifecycleHelperSocketPath }),
+    unit: agentUnit({
+      ...options,
+      mode,
+      lifecycleProfilePath,
+      lifecycleHelperSocketPath,
+      bootstrapSshCredentialPath
+    }),
     auxiliaryUnits: [
       { path: AGENT_SOCKET_UNIT_PATH, unit: agentSocketUnit(options) },
       { path: AGENT_SOCKET_PROXY_UNIT_PATH, unit: agentSocketProxyUnit(options) },
@@ -11639,6 +11666,7 @@ var SEED_CREDENTIAL = `${CREDS}/seed-sync-root.cred`;
 var BACKUP_RECOVERY_CREDENTIAL = `${CREDS}/backup-recovery-root.cred`;
 var WARP_CLIENT_ID_CREDENTIAL = `${CREDS}/warp-auth-client-id.cred`;
 var WARP_CLIENT_SECRET_CREDENTIAL = `${CREDS}/warp-auth-client-secret.cred`;
+var BOOTSTRAP_SSH_CREDENTIAL = `${CREDS}/bootstrap-ssh-key.cred`;
 var PLATFORM_ENROL_SOURCE = "/run/forgezero-platform-enrol-token";
 var DB_MODE_EVIDENCE = "/var/lib/forgezero-cluster/server-mode.json";
 var LIFECYCLE_PROFILE = "/etc/forgezero/lifecycle.json";
@@ -11701,6 +11729,20 @@ function validateBootstrapConfig(value) {
     }
     if (!value.enrolTokenFile)
       throw new Error("tenant bootstrap requires --enrol-token-file");
+    if (value.bootstrapRunner) {
+      if (!value.bootstrapRunner.sshPrivateKeyFile.startsWith("/") || /[\r\n]/.test(value.bootstrapRunner.sshPrivateKeyFile)) {
+        throw new Error("bootstrap runner SSH private-key file must be absolute");
+      }
+      let targetTelemetry;
+      try {
+        targetTelemetry = new URL(value.bootstrapRunner.targetTelemetryEndpoint);
+      } catch {
+        throw new Error("bootstrap target telemetry endpoint is malformed");
+      }
+      if (targetTelemetry.protocol !== "https:" || targetTelemetry.username || targetTelemetry.password || targetTelemetry.search || targetTelemetry.hash || targetTelemetry.port && targetTelemetry.port !== "443") {
+        throw new Error("bootstrap target telemetry must be public HTTPS on port 443");
+      }
+    }
     return value;
   }
   if (!PLATFORM_BOOTSTRAP_PROFILES.includes(value.profile))
@@ -11762,7 +11804,11 @@ function validateBootstrapConfig(value) {
 }
 function planBootstrap(input, initialized = false) {
   const config = validateBootstrapConfig(structuredClone(input));
-  const software = config.kind === "tenant" ? [...config.software ?? [], ...config.installCloudflared ? [{ id: "cloudflared", version: "2026.7.3" }] : []] : [
+  const software = config.kind === "tenant" ? [
+    ...config.software ?? [],
+    ...config.bootstrapRunner && !config.software?.some(({ id: id2 }) => id2 === "openssh-client") ? [{ id: "openssh-client", version: "ubuntu-26.04" }] : [],
+    ...config.installCloudflared ? [{ id: "cloudflared", version: "2026.7.3" }] : []
+  ] : [
     ...config.firewall.enabled ? [{ id: "ufw", version: "ubuntu-26.04" }] : [],
     { id: "bun", version: "1.3.14" },
     { id: "nginx", version: "ubuntu-26.04" },
@@ -11997,6 +12043,10 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
   const alreadyEnrolled = host.exists("/var/lib/forgezero/enrolment.json");
   host.mkdir(CREDS, 448);
   host.mkdir("/var/lib/forgezero", 448);
+  if (config.kind === "tenant" && config.bootstrapRunner && !host.exists(BOOTSTRAP_SSH_CREDENTIAL)) {
+    await seal(host, "bootstrap-ssh-key", BOOTSTRAP_SSH_CREDENTIAL, privateFile(host, config.bootstrapRunner.sshPrivateKeyFile, "bootstrap runner SSH private key"));
+    host.remove(config.bootstrapRunner.sshPrivateKeyFile);
+  }
   if (cloudflare?.warp) {
     await seal(host, "warp-auth-client-id", WARP_CLIENT_ID_CREDENTIAL, cloudflare.warp.clientId);
     await seal(host, "warp-auth-client-secret", WARP_CLIENT_SECRET_CREDENTIAL, cloudflare.warp.clientSecret);
@@ -12196,7 +12246,8 @@ function strictBootstrapDocument(value) {
     "cloudflareHandoff",
     "realm",
     "enrolTokenFile",
-    "software"
+    "software",
+    "bootstrapRunner"
   ], "bootstrap config");
   if (root.kind === "platform") {
     exactKeys2(root.firewall, ["enabled", "sshPort", "privateCidrs"], "firewall config");
@@ -12261,6 +12312,8 @@ function strictBootstrapDocument(value) {
       exactKeys2(environment.cloudflare.warp, ["organization", "virtualNetworkId", "deviceProfileId"], "Cloudflare WARP runtime config");
     }
   } else if (root.kind === "tenant") {
+    if (root.bootstrapRunner !== undefined)
+      exactKeys2(root.bootstrapRunner, ["sshPrivateKeyFile", "targetTelemetryEndpoint"], "bootstrap runner config");
     for (const key of ["environment", "profile", "computeReference", "database", "platformEnrolTokenFile", "runtime", "cloudflareHandoff"]) {
       if (root[key] !== undefined && key !== "profile")
         throw new Error(`tenant bootstrap cannot contain ${key}`);
@@ -12355,6 +12408,9 @@ function localBootstrapHost() {
         generateGitIdentity: true,
         pullDeployments: true,
         pullMigrations: config.kind === "platform",
+        pullBootstrap: config.kind === "tenant" && Boolean(config.bootstrapRunner),
+        bootstrapSshCredentialPath: config.kind === "tenant" && config.bootstrapRunner ? BOOTSTRAP_SSH_CREDENTIAL : undefined,
+        bootstrapTargetTelemetryEndpoint: config.kind === "tenant" ? config.bootstrapRunner?.targetTelemetryEndpoint : undefined,
         lifecycleProfilePath: config.kind === "platform" ? LIFECYCLE_PROFILE : undefined,
         ...config.kind === "platform" && config.runtime.environment.cloudflare?.warp ? {
           warpOrganization: config.runtime.environment.cloudflare.warp.organization,
@@ -14140,6 +14196,7 @@ function interactiveBootstrap(kind) {
   if (!process.stdin.isTTY)
     throw new Error("non-interactive bootstrap requires --bootstrap-config <private-json-file>");
   if (kind === "tenant") {
+    const runnerKey = bootstrapAnswer("Bootstrap runner SSH private-key file (blank to disable)", "");
     return {
       kind,
       apiUrl: bootstrapAnswer("Platform API URL"),
@@ -14147,7 +14204,11 @@ function interactiveBootstrap(kind) {
       nodeHostname: bootstrapAnswer("Node hostname", hostname()),
       telemetryEndpoint: bootstrapAnswer("Public HTTPS OTLP endpoint"),
       enrolTokenFile: bootstrapAnswer("Root-only enrolment token file"),
-      profile: bootstrapAnswer("Deploy profile", "app")
+      profile: bootstrapAnswer("Deploy profile", "app"),
+      ...runnerKey ? { bootstrapRunner: {
+        sshPrivateKeyFile: runnerKey,
+        targetTelemetryEndpoint: bootstrapAnswer("Public HTTPS OTLP endpoint for bootstrapped targets")
+      } } : {}
     };
   }
   const environment = bootstrapAnswer("Environment (production/development)", "production");

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export type { DeploymentPullOptions, RemoteDeploymentClaim, PullResult } from '.
 export { pullProvisioningOnce, startProvisioningPull } from './provisioning-pull';
 export type { CreateRemoteProvisionClaim, ProvisioningPullOptions, RemoteProvisionClaim, GuestAccess, ProvisionPullResult, ProvisionRunner, ProvisionResult } from './provisioning-pull';
 export { pullMigrationOnce, startMigrationPull } from './migration-pull';
+export { executeSshBootstrap, pullSshBootstrapOnce, startSshBootstrapPull } from './ssh-bootstrap';
+export type { RemoteSshBootstrapClaim, SshBootstrapPullOptions, SshBootstrapResult } from './ssh-bootstrap';
 export type { MigrationAction, MigrationEvidence, MigrationNetwork, MigrationPullOptions, MigrationPullResult, RemoteMigrationClaim } from './migration-pull';
 export { enrolGuestIdentity, loadGuestBinding } from './guest-enrolment';
 export type { GuestBinding, GuestEnrolmentOptions } from './guest-enrolment';

package/dist/metal-bootstrap.js

@@ -293,7 +293,7 @@ function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
 }
 
 // src/version.ts
-var VERSION = "0.1.35";
+var VERSION = "0.1.36";
 
 // src/metal-bootstrap.ts
 var PROFILE_PATH = "/etc/forgezero/metal.json";

package/dist/provision.d.ts

@@ -100,6 +100,10 @@ export interface UnitOptions {
     runnerPublicTcpPorts?: readonly number[];
     /** Enable PQ-authenticated lifecycle claims through a constrained root helper. */
     pullMigrations?: boolean;
+    /** Claim API-owned SSH bootstrap jobs; the private key stays a systemd credential on this runner. */
+    pullBootstrap?: boolean;
+    bootstrapSshCredentialPath?: string;
+    bootstrapTargetTelemetryEndpoint?: string;
     /** Root-owned declarative lifecycle profile; never supplied by a migration claim. */
     lifecycleProfilePath?: string;
     lifecycleHelperSocketPath?: string;

package/dist/provision.js

@@ -673,6 +673,7 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 
 // src/software.ts
 import { readFileSync as readFileSync3 } from "node:fs";
+var PINNED_BUN_VERSION = "1.3.14";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
@@ -684,7 +685,8 @@ var SOFTWARE_CATALOG = [
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
-  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
   {
@@ -711,6 +713,11 @@ var UBUNTU_2604_X64 = [
     requirement: { id: "ufw", version: "ubuntu-26.04" },
     check: "command -v ufw >/dev/null",
     install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
+  },
+  {
+    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
+    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
   }
 ];
 function observeSoftwareHost(osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch) {
@@ -735,7 +742,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };
@@ -884,7 +891,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.35";
+var VERSION3 = "0.1.36";
 
 // src/egress-policy.ts
 import { realpathSync } from "node:fs";
@@ -1419,7 +1426,12 @@ function agentUnit(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
+  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapTargetTelemetryEndpoint);
+  if ([options.pullBootstrap, options.bootstrapSshCredentialPath, options.bootstrapTargetTelemetryEndpoint].some(Boolean) && !bootstrapEnabled) {
+    throw new Error("bootstrap pull, SSH credential and target telemetry endpoint must be supplied together");
+  }
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
+  const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
   const warpValues = [
     options.warpOrganization,
     options.warpClientIdCredentialPath,
@@ -1485,6 +1497,9 @@ function agentUnit(options) {
     options.publicApiUrl ? `FZ_PUBLIC_API_URL=${options.publicApiUrl}` : null,
     options.pullDeployments ? "FZ_DEPLOY_PULL=true" : null,
     options.pullMigrations ? "FZ_MIGRATION_PULL=true" : null,
+    options.pullBootstrap ? "FZ_BOOTSTRAP_PULL=true" : null,
+    options.pullBootstrap ? "FZ_BOOTSTRAP_SSH_KEY_CREDENTIAL=bootstrap-ssh-key" : null,
+    options.pullBootstrap ? `FZ_BOOTSTRAP_TARGET_OTLP_ENDPOINT=${options.bootstrapTargetTelemetryEndpoint}` : null,
     `FZ_AGENT_UPDATE_SOCKET=${DEFAULT_AGENT_UPDATE_SOCKET}`,
     options.pullMigrations ? `FZ_LIFECYCLE_HELPER_SOCKET=${lifecycleHelperSocketPath}` : null
   ].filter((line) => line !== null);
@@ -1492,6 +1507,8 @@ function agentUnit(options) {
     environment.push(`HOME=${deployRoot}/agent-home`, `XDG_CACHE_HOME=${deployRoot}/cache`);
   }
   const gitCredential = options.gitCredentialPath ? `LoadCredentialEncrypted=git-deploy-key:${options.gitCredentialPath}
+` : "";
+  const bootstrapCredential = bootstrapEnabled ? `LoadCredentialEncrypted=bootstrap-ssh-key:${bootstrapSshCredentialPath}
 ` : "";
   const projectCredentials = Object.entries(deploymentCredentials).map(([name, path]) => `LoadCredentialEncrypted=${name}:${path}`).join(`
 `);
@@ -1546,7 +1563,7 @@ User=${user}
 Group=${VAULT_GROUP}
 ${deploymentGroup}
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
-${gitCredential}${projectCredentials}${projectCredentials ? `
+${gitCredential}${bootstrapCredential}${projectCredentials}${projectCredentials ? `
 ` : ""}${snpPrepare}ExecStart=${bin}
 Restart=always
 RestartSec=2
@@ -1601,6 +1618,10 @@ function planProvision(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
+  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapTargetTelemetryEndpoint);
+  if ([options.pullBootstrap, options.bootstrapSshCredentialPath, options.bootstrapTargetTelemetryEndpoint].some(Boolean) && !bootstrapEnabled) {
+    throw new Error("bootstrap pull, SSH credential and target telemetry endpoint must be supplied together");
+  }
   const warpValues = [
     options.warpOrganization,
     options.warpClientIdCredentialPath,
@@ -1626,13 +1647,20 @@ function planProvision(options) {
   const gitPublicKeyDir = gitPublicKeyPath?.replace(/\/[^/]+$/, "");
   const lifecycleProfilePath = lifecycleEnabled ? systemdPath(options.lifecycleProfilePath, "lifecycle profile") : undefined;
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
+  const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
   const warpClientIdCredentialPath = warpEnabled ? systemdPath(options.warpClientIdCredentialPath, "WARP client-id credential") : undefined;
   const warpClientSecretCredentialPath = warpEnabled ? systemdPath(options.warpClientSecretCredentialPath, "WARP client-secret credential") : undefined;
   return {
     mode,
     reason: reasonFor(mode),
     unitPath: UNIT_PATH,
-    unit: agentUnit({ ...options, mode, lifecycleProfilePath, lifecycleHelperSocketPath }),
+    unit: agentUnit({
+      ...options,
+      mode,
+      lifecycleProfilePath,
+      lifecycleHelperSocketPath,
+      bootstrapSshCredentialPath
+    }),
     auxiliaryUnits: [
       { path: AGENT_SOCKET_UNIT_PATH, unit: agentSocketUnit(options) },
       { path: AGENT_SOCKET_PROXY_UNIT_PATH, unit: agentSocketProxyUnit(options) },

package/dist/software-helper.js

@@ -1,5 +1,6 @@
 // src/software.ts
 import { readFileSync } from "node:fs";
+var PINNED_BUN_VERSION = "1.3.14";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
@@ -11,7 +12,8 @@ var SOFTWARE_CATALOG = [
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
-  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
   {
@@ -38,6 +40,11 @@ var UBUNTU_2604_X64 = [
     requirement: { id: "ufw", version: "ubuntu-26.04" },
     check: "command -v ufw >/dev/null",
     install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
+  },
+  {
+    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
+    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
   }
 ];
 function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
@@ -62,7 +69,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };

package/dist/software.d.ts

@@ -1,6 +1,6 @@
 export type CatalogStatus = 'testing' | 'active' | 'retired';
 export type DeploymentChannel = 'development' | 'production';
-export type SoftwareId = 'bun' | 'nginx' | 'arangodb' | 'cloudflared' | 'ufw';
+export type SoftwareId = 'bun' | 'nginx' | 'arangodb' | 'cloudflared' | 'ufw' | 'openssh-client';
 /** Repository input is a catalogue coordinate, never a root command. */
 export interface SoftwareRequirement {
     id: SoftwareId;
@@ -32,6 +32,8 @@ export interface SoftwareCommandResult {
     output: string;
 }
 export type SoftwareExec = (command: string) => Promise<SoftwareCommandResult>;
+export declare const PINNED_BUN_VERSION = "1.3.14";
+export declare const BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 /** Public, command-free catalog. Root strategies remain private below. */
 export declare const OS_CATALOG: readonly OsCatalogEntry[];
 export declare const SOFTWARE_CATALOG: readonly SoftwareCatalogEntry[];

package/dist/software.js

@@ -1,5 +1,6 @@
 // src/software.ts
 import { readFileSync } from "node:fs";
+var PINNED_BUN_VERSION = "1.3.14";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
@@ -11,7 +12,8 @@ var SOFTWARE_CATALOG = [
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
-  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
   {
@@ -38,6 +40,11 @@ var UBUNTU_2604_X64 = [
     requirement: { id: "ufw", version: "ubuntu-26.04" },
     check: "command -v ufw >/dev/null",
     install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
+  },
+  {
+    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
+    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
   }
 ];
 function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
@@ -62,7 +69,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };
@@ -108,5 +115,7 @@ export {
   observeSoftwareHost,
   ensureSoftwareRequirements,
   SOFTWARE_CATALOG,
-  OS_CATALOG
+  PINNED_BUN_VERSION,
+  OS_CATALOG,
+  BUN_INSTALLER_SHA256
 };

package/dist/ssh-bootstrap.d.ts

@@ -0,0 +1,72 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
+import { type GitHostResolver } from './git-egress';
+export interface RemoteSshBootstrapClaim {
+    computeKey: string;
+    computeReference: string;
+    claimToken: string;
+    claimExpiresAtTs: number;
+    attempt: number;
+    realm: string;
+    projectKey: string;
+    environmentKey: string;
+    target: {
+        host: string;
+        port: number;
+        user: string;
+        hostKeySha256: string;
+        nodeHostname: string;
+    };
+    enrolmentToken: string;
+}
+export interface BootstrapCommandResult {
+    exitCode: number;
+    output: string;
+}
+export type BootstrapCommand = (argv: readonly string[], options?: {
+    stdin?: string;
+    secret?: boolean;
+}) => Promise<BootstrapCommandResult>;
+export interface SshBootstrapPullOptions {
+    apiUrl: string;
+    platformApiUrl: string;
+    nodeKey: string;
+    keys: NodeKeyPair;
+    sshKeyPath: string;
+    targetTelemetryEndpoint: string;
+    fzCliPath?: string;
+    fzAgentPath?: string;
+    exec?: BootstrapCommand;
+    fetch?: (input: URL, init: RequestInit) => Promise<Response>;
+    intervalMs?: number;
+    requestTimeoutMs?: number;
+    now?: () => number;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    onEvent?: (event: string, detail?: unknown) => void;
+    telemetry?: AgentOperationTelemetry;
+    resolveHost?: GitHostResolver;
+}
+export type SshBootstrapResult = {
+    status: 'idle';
+} | {
+    status: 'completed';
+    computeKey: string;
+    attempt: number;
+} | {
+    status: 'failed';
+    computeKey: string;
+    attempt: number;
+    failureCode: string;
+};
+export declare class SshBootstrapError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+/** Execute one job without ever putting the enrolment token or SSH key in argv. */
+export declare function executeSshBootstrap(claim: RemoteSshBootstrapClaim, options: Pick<SshBootstrapPullOptions, 'platformApiUrl' | 'sshKeyPath' | 'targetTelemetryEndpoint' | 'fzCliPath' | 'fzAgentPath' | 'exec' | 'resolveHost'>): Promise<void>;
+export declare function pullSshBootstrapOnce(options: SshBootstrapPullOptions): Promise<SshBootstrapResult>;
+export declare function startSshBootstrapPull(options: SshBootstrapPullOptions): {
+    stop(): Promise<void>;
+    readonly active: boolean;
+};

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.35";
+export declare const VERSION = "0.1.36";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@forgezero/agent",
-	"version": "0.1.35",
+	"version": "0.1.36",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",

package/schema/deploy-v2.json

@@ -28,7 +28,7 @@
               "additionalProperties": false,
               "required": ["id", "version"],
               "properties": {
-                "id": { "enum": ["bun", "nginx", "arangodb", "cloudflared", "ufw"] },
+                "id": { "enum": ["bun", "nginx", "arangodb", "cloudflared", "ufw", "openssh-client"] },
                 "version": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$" }
               }
             }