Monetize: Provider provisioning

Turn a published manifest into an ordered, auditable install that makes a machine a compute provider node.

The provisioning runner turns a ProviderProvisioningManifest (apiVersion: node-provider.peaq.network/v1alpha1) into an ordered, auditable install that provisions a machine as a compute provider node. All provider-specific complexity lives in the manifest; the runner only understands the schema’s generic vocabulary: phases, steps, prompts, captures, secrets, and verification probes. It never hardcodes any provider’s setup.

Provisioning ships in @peaqos/peaq-os-sdk 0.5.0+ (JS/TS) and peaq-os-sdk 0.5.0+ (Python), and runs on the machine itself.

Design invariants

• Verification, not exit codes, defines success. A machine is a live provider only when the manifest’s success probes pass.
• Secrets never leak. Secret inputs, secret captures, and per-step redaction are applied before anything is streamed, logged, or persisted.
• Sudo is explicit and scoped. Auto mode elevates only the commands the manifest marks, and only within the operator’s granted allowlist.
• Handoffs are real stops. Owner-action steps block until the owner confirms; a confirmation is never synthesised.
• Payout context defaults to the machine wallet, never the operator’s. The runner exposes the machine wallet address as generic context; the manifest decides how it maps into commission fields.

The lifecycle

The namespace is client.provisioning in JS/TS and the peaq_os_sdk.provisioning module in Python; every method is also importable standalone.

Fetch a manifest

Manifests are hosted on a public repo and pulled on demand. The repo base URL is configuration, never hardcoded. The JS SDK is YAML-agnostic (pass a parse function from a YAML library you already depend on); the Python SDK parses YAML itself.

JavaScript

import { parse as parseYaml } from "yaml";

const { manifest, resolvedVersion } = await client.provisioning.fetchManifest(
  { repoBaseUrl: MANIFEST_REPO_URL, parse: parseYaml },
  { provider: "akash" }, // omit version to resolve "latest"
);

• Version: pass an explicit version or resolve "latest"; the concrete version is read back from the document and recorded for reproducibility.
• Integrity: pass an expected digest (expectedDigest in JS, checksum in Python) to verify the fetched document; a mismatch fails closed and the manifest is never returned or used. One Python caveat: the fetched bytes are written to cache_dir before the digest check, so clear the cache after a mismatch (or keep checksum on every read, including offline=True ones); a later cache read without it would return the rejected document.
• Pinning: request the raw source bytes (includeSource: true in JS) and compute a deterministic sha256:<hex> pin with manifestPinDigest, so a later verify can prove it ran against the exact document that provisioned the node. The CLI’s state file uses this pin.
• Cache and offline: caching is opt-in. Configure it (cache in JS, cache_dir in Python) and a network fetch stores the raw document for offline mode to reuse; configure nothing and nothing is stored, so offline mode has nothing to read. The document is re-validated against the schema on every read.

Manifest YAML keys are camelCase (apiVersion, onFailure, allowedCommands). The JS SDK keeps them camelCase; the Python SDK maps them onto snake_case dataclass fields (validation.min/max become min_value/max_value).

Resolve inputs

resolveInputs / resolve_inputs merges caller values with the manifest’s declared inputs: it enforces required, applies defaults, type-checks every declared type (string, int, bool, enum, url, hostname, bytesize, array, object), and applies validation rules (values, pattern, min, max). Inputs marked secret: true are flagged and never echoed in errors.

Pre-flight is a gate

runPreflight / run_preflight runs each check and reports passed, blocked, and per-check results. A check with onFailure: block that fails blocks provisioning; onFailure: warn surfaces without blocking. A privileged check that cannot be auto-run is surfaced for the owner, and a surfaced blocking check still blocks the gate (fail closed). provision refuses to start while the gate is blocked.

Provision: manual vs auto mode

provision runs in manual or auto mode (mode is required on provision in both SDKs), and every step also declares its own mode (manual, auto, or both). The manifest decides; the runner honours it.

Mode	Behaviour
manual	Step-by-step, but the confirmation gate is yours to wire. Python requires on_confirm_step: it is called before each command and returning False stops the run resumably; without the callback the first command step raises ProvisioningError and leaves no resume state (pass lambda e: True for an unattended manual run). The JS runner has no confirmation callback: onStep is informational and cannot decline a step. The CLI gives you the interactive gate without building it.
auto	End-to-end execution. Requires a sudo grant for privileged steps; the exact command is emitted before each run so the owner can audit it.

Sudo is explicit per command (never / optional / required). The runner never elevates a command the manifest does not mark. In auto mode, a sudo: required command runs only under a sudo grant matched by prefix against the manifest’s allowedCommands; the effective grant is the intersection of the two (the narrower side wins), so an operator can scope down but the grant can never broaden beyond the manifest. A privileged command outside the grant fails closed: it is not run unprivileged.

JavaScript

import 'dotenv/config';
import { promises as fs } from "node:fs";
import { createInterface } from "node:readline/promises";
import { parse as parseYaml } from "yaml";
import { LocalShellExecutor, PeaqosClient } from "@peaqos/peaq-os-sdk";

const client = PeaqosClient.fromEnv();
const MANIFEST_REPO_URL = process.env.MANIFEST_REPO_URL!; // base URL of the manifest repo

const { manifest } = await client.provisioning.fetchManifest(
  { repoBaseUrl: MANIFEST_REPO_URL, parse: parseYaml },
  { provider: "akash" },
);

// Show the owner the handoff instructions and return what they type.
async function promptOwner(instructions: string, expectedConfirmation: string): Promise<string> {
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  const answer = await rl.question(`${instructions}\nType "${expectedConfirmation}" to continue: `);
  rl.close();
  return answer;
}

const result = await client.provisioning.provision(manifest, {
  mode: "auto",
  executor: new LocalShellExecutor(),
  values: { providerDomain: "provider.example.com", walletPassword: "…" },
  sudoGrant: { allowedCommands: ["apt-get", "kubectl", "provider-services"] },
  machineWalletAddress: "0x…", // exposed to the manifest as context.machineWalletAddress
  writeFile: async (r) => fs.writeFile(r.path, r.content),
  onOwnerAction: async (r) => promptOwner(r.instructions, r.expectedConfirmation),
});

The sudo grant is a scoping and audit aid, not a security boundary. A granted program can still run arbitrary code through its own arguments, and auto mode elevates unattended, so run only a manifest you trust: fetch it with an expected digest first, and treat auto mode on an unverified remote manifest as remote root execution.

Step kinds

Kind	Behaviour
command	Run the command with the step’s sudo, cwd, user, and timeout settings; capture outputs per captures.
render-file	Render a file (path, owner, mode, interpolated content) to disk. Content is never echoed. A privileged write is grant-scoped like a command (matched as render-file <path>).
download	Fetch a resource; integrity is verified via the step’s checksum (sha256, bare hex or sha256:<hex>) in both SDKs.
owner-action	Pause, emit instructions, and wait for the declared confirmation. Never auto-confirmed.
verify	Run an inline command. JS evaluates the step’s expect (default: exit code 0). Python has no step-level expect and passes on exit code 0 alone, so put output assertions in verification probes, not in a verify step.

Prompts, captures, and the machine wallet

Interactive prompts fill from input (a resolved input), capture (an earlier step’s value), or owner (answered interactively, never auto-filled). Captured values thread by key into later steps, verification, and post-provision. The runner exposes the machine wallet address as run context (context.machineWalletAddress in JS, {{ context.machine_wallet_address }} in Python, supplied via context=); the manifest declares how that maps into any commission or payout field. The runner itself holds no commission semantics.

Owner-action handoffs

Wallet funding, DNS changes, hardware-wallet signing, and SSH access confirmations are owner-action steps: real pause points. The runner emits the interpolated (redacted) instructions and blocks until the owner returns the declared confirmation. A missing handler or a mismatched answer fails the step.

Idempotency and resumability

Each step may declare idempotency: a check command runs first and skips the step when the effect is already present, and rerun policy is safe, unsafe, or requires-confirmation. The confirmation handler differs per SDK: JS prompts via onRerunConfirm and raises StepExecutionError when the handler is missing, while Python calls on_confirm_rerun and, when it is omitted, silently skips a requires-confirmation step whose check passes. Pass the handler in Python if the re-run decision matters.

An interrupted run always leaves a resumable state: provision returns a resume state, attaches one to the failure error, and (optionally) emits it at every step boundary via onStateChange / on_state_change, so a caller can checkpoint durably as the run progresses. The state is JSON-round-trippable and carries a schema version, the completed step ids (keyed by phase/step), a cursor, and the resolved non-secret inputs and captures. A resumed run skips completed steps and restores the non-secret captures.

The boundary callback also fires at the pre-confirmation owner-action pause, with the owner-action excluded: a run killed at a funding or DNS handoff resumes by re-entering that handoff, never by skipping it.

JavaScript

try {
  await client.provisioning.provision(manifest, {
    ...options,
    onStateChange: (state) => checkpoint.write(state), // durable per-step checkpoint
  });
} catch (err) {
  if (err instanceof StepExecutionError && err.resumeState) {
    await client.provisioning.provision(manifest, {
      ...options,
      resumeState: err.resumeState,
      resumeSecrets: { walletKey: "…" }, // re-supply secret captures if needed
    });
  }
}

Secret captures are never persisted, in plaintext or otherwise; only their key names are recorded. On resume, if a remaining step needs a secret from an already-completed producer, the runner re-runs that producer when its rerun policy is safe, takes a caller-re-supplied value via resumeSecrets / resume_secrets otherwise, and fails with ResumeNotPossibleError (naming the step and the missing keys) when neither applies. A step never interpolates a missing or empty secret.

Verification closes the loop

verifyProvisioning / verify_provisioning runs the manifest’s probes. Success requires every probe in verification.success.allOf to pass; exit-zero installs alone never count. A privileged probe that cannot be elevated is not run unprivileged: it is reported as failed. ensureVerified in JS/TS, and the result’s own raise_if_failed() in Python, raises VerificationFailedError (listing the failed probes) unless verification succeeded; report the node live only when it does not raise.

Post-provision operations

runPostProvision / run_post_provision runs one opt-in operator utility by id (tail logs, check balance, and similar), honouring its mode, sudo policy, and actor. These are helpers only, never part of the success gate.

Secrets and redaction

A run-scoped redaction registry holds every secret input value plus the declared extraction pattern of every secret capture, registered before its step runs. Every streamed chunk, event, captured output, rendered-file echo, and error message passes through redaction before it leaves the SDK. A secret stdout/stderr capture with no pattern suppresses raw stream emission entirely. Typed errors carry only structural metadata (ids, paths, exit codes), never secret material.

Redaction is automatic inside provision, not outside it. verifyProvisioning / verify_provisioning and JS runPreflight take their own optional redaction registry and seed nothing from your resolved inputs, so pass the registry yourself or run them through the CLI. Call them without it and a probe command that interpolates a secret is emitted, executed, and returned in the clear; Python’s run_preflight does seed redaction from the inputs you hand it.

Errors

Error	Raised when
ManifestFetchError	Network failure, 404, timeout, or checksum mismatch while fetching
ManifestSchemaError	The manifest fails structural validation
ProvisioningValidationError	An input fails type or validation rules
PreflightBlockedError	A blocking pre-flight check failed
StepExecutionError	A step failed, timed out, or was disallowed; carries the resume state
VerificationFailedError	Required probes did not all pass

Related

• Monetize function: where provisioning fits in the flow
• Heartbeat SDK reference: report presence once provisioned
• Monetization opt-in API