> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Monetize: Provider provisioning
> The schema-driven provisioning runner: turn a published manifest into an ordered, auditable install that makes a machine a compute provider node.
export const KeyTerms = ({all = {}, ids = [], title = "Key terms in this guide"}) =>
{title}
{ids.map(id => {
const t = all[id] || ({});
return
{t.term}. {t.def}
;
})}
;
export const G = {
onchain: {
id: "onchain",
cat: "chain-infra",
term: "On-chain vs off-chain",
def: "On-chain means written to the shared public ledger every machine agrees on: permanent and readable by anyone. Off-chain means kept on a normal private server instead."
},
blockchain: {
id: "blockchain",
cat: "chain-infra",
term: "Chain / blockchain",
def: "A shared, tamper-resistant public database maintained by a whole network of computers with no single owner. Different chains are separate such networks."
},
peaqChain: {
id: "peaqChain",
cat: "chain-infra",
term: "peaq chain",
def: "The machine-focused blockchain peaqOS uses as home base for identity and credit records."
},
transaction: {
id: "transaction",
cat: "chain-infra",
term: "Transaction (tx) / tx hash",
def: "A single signed request that changes the ledger. Its hash is a unique, receipt-like ID you can use to look it up later."
},
rpcUrl: {
id: "rpcUrl",
cat: "chain-infra",
term: "RPC URL / endpoint",
def: "The network address your code calls to read from or write to a chain, like the base URL of the chain's API server."
},
mainnet: {
id: "mainnet",
cat: "chain-infra",
term: "Mainnet / testnet (agung)",
def: "Mainnet is the real, live network where tokens have real value. Testnet is a free practice copy with worthless tokens; peaq's is called agung."
},
evm: {
id: "evm",
cat: "chain-infra",
term: "EVM / EVM-compatible",
def: "The Ethereum Virtual Machine: the standard runtime many chains share, so the same 0x... addresses and tools work across all of them. peaq is EVM-compatible."
},
node: {
id: "node",
cat: "chain-infra",
term: "Node (RPC node)",
def: "A server running the blockchain software that holds a copy of the ledger and answers queries. NOT a ROS 2 node, despite the shared word."
},
chainId: {
id: "chainId",
cat: "chain-infra",
term: "Chain ID",
def: "A number that uniquely labels a chain so software doesn't confuse networks (peaq is 3338, Base is 8453)."
},
precompile: {
id: "precompile",
cat: "chain-infra",
term: "Precompile",
def: "A built-in function baked into the chain at a fixed address that acts like a contract but runs as faster native code. The batch one bundles several actions into one all-or-nothing transaction."
},
dataHash: {
id: "dataHash",
cat: "chain-infra",
term: "Data hash (keccak256)",
def: "A short, fixed-length fingerprint of a file, stored on-chain instead of the file itself, so data can be verified later while the raw data stays off-chain."
},
wallet: {
id: "wallet",
cat: "wallet-keys",
term: "Wallet",
def: "An account on the chain, identified by a public address, that holds a machine's funds and approves its actions. Really just a pair of keys, not a place money is stored."
},
keypair: {
id: "keypair",
cat: "wallet-keys",
term: "Keypair",
def: "The two matched secrets behind a wallet: a public address you can share, and a private key you keep secret that signs actions."
},
privateKey: {
id: "privateKey",
cat: "wallet-keys",
term: "Private key",
def: "The secret string that proves you control a wallet. Anyone who has it has full control, like a master password that can never be reset."
},
sign: {
id: "sign",
cat: "wallet-keys",
term: "Sign / signature",
def: "Using your private key to produce a cryptographic stamp proving you approved a specific action, without ever revealing the key."
},
signer: {
id: "signer",
cat: "wallet-keys",
term: "Signer / signing identity",
def: "The wallet whose private key authorizes an action: the account the network treats as the one taking it. NOT a file or an app."
},
address: {
id: "address",
cat: "wallet-keys",
term: "Address (0x...)",
def: "The public 0x... identifier of a wallet or contract you can freely share so others can send to it or look it up, like an account number."
},
eoa: {
id: "eoa",
cat: "wallet-keys",
term: "EOA (externally owned account)",
def: "A plain wallet controlled directly by a private key, as opposed to one controlled by code. Here, the account that IS the machine."
},
ows: {
id: "ows",
cat: "wallet-keys",
term: "OWS / wallet vault",
def: "An open standard for storing wallet keys in an encrypted local file (a vault) with a backup phrase and an activity log, instead of a bare key in a text file."
},
passphrase: {
id: "passphrase",
cat: "wallet-keys",
term: "Passphrase (OWS_PASSPHRASE)",
def: "The password that unlocks the encrypted wallet vault so its key can be used to sign."
},
mnemonic: {
id: "mnemonic",
cat: "wallet-keys",
term: "Mnemonic / seed phrase",
def: "A list of 12 or 24 ordinary words that encodes a wallet's secret key, used to back it up and recover it. Whoever has the words controls the wallet."
},
derivation: {
id: "derivation",
cat: "wallet-keys",
term: "Derivation path",
def: "The deterministic recipe that turns one backup phrase into many specific keys and addresses, one per network or index."
},
challenge: {
id: "challenge",
cat: "wallet-keys",
term: "Challenge (sign-to-prove)",
def: "A login-style handshake: the server sends a random message, you sign it with your key, and the signature proves you control the account without sending the key."
},
eip191: {
id: "eip191",
cat: "wallet-keys",
term: "EIP-191 / personal_sign",
def: "A standard way to sign a plain message to prove you control an account, without sending any on-chain transaction."
},
did: {
id: "did",
cat: "identity",
term: "DID / peaqID",
def: "A globally unique, self-owned ID for a machine that lives on the chain and isn't issued by any single company. peaqID is peaq's version, written did:peaq:0x..."
},
register: {
id: "register",
cat: "identity",
term: "Register a machine",
def: "Putting a machine on the network for the first time, which gives it an ID, a DID, an ownership token, and a locked deposit. registerMachine is self-managed; registerFor is on someone else's behalf."
},
machineId: {
id: "machineId",
cat: "identity",
term: "Machine ID",
def: "The number the network assigns your machine when it registers, used as its handle in every later call."
},
ownerOperator: {
id: "ownerOperator",
cat: "identity",
term: "Owner / operator",
def: "The owner owns a machine; the operator runs it. They can be the same account (self-managed) or different (proxy-managed)."
},
proxyOperator: {
id: "proxyOperator",
cat: "identity",
term: "Proxy operator",
def: "One account that registers and manages many machines on behalf of their owners, so a fleet operator can handle a whole fleet from one wallet."
},
didAttributes: {
id: "didAttributes",
cat: "identity",
term: "DID attributes",
def: "Public name-value facts (a docs link, a data endpoint) attached to a machine's DID and stored on-chain for anyone to read. Writing them is a separate transaction from registration."
},
pairing: {
id: "pairing",
cat: "identity",
term: "Pairing / pairing token",
def: "The verified link between an AI agent and a machine, set up by signing a challenge. The pairing token is the signed credential the agent sends with each request, like a temporary access badge."
},
hardwareAttestation: {
id: "hardwareAttestation",
cat: "identity",
term: "Hardware attestation",
def: "A tamper-resistant chip on the machine cryptographically vouching that it's genuine hardware, so its identity can't be faked in software. This is the Verify layer."
},
gas: {
id: "gas",
cat: "tokens-economics",
term: "Gas",
def: "The small fee, paid in the chain's token, that every action writing to the ledger costs, like a per-write transaction cost."
},
peaqToken: {
id: "peaqToken",
cat: "tokens-economics",
term: "PEAQ (token)",
def: "The peaq network's own token, used to pay gas fees and to lock up as the deposit when registering a machine."
},
gasStation: {
id: "gasStation",
cat: "tokens-economics",
term: "Gas Station / faucet",
def: "A peaq service that hands a brand-new, empty wallet a tiny starting amount of tokens so it can afford its first network fees. Gated by 2FA."
},
bond: {
id: "bond",
cat: "tokens-economics",
term: "Bond",
def: "A refundable deposit (currently 1 PEAQ) you lock up to register a machine, proving skin in the game, like a security deposit. Bonded means the deposit is in place."
},
nft: {
id: "nft",
cat: "tokens-economics",
term: "NFT",
def: "A unique, one-of-a-kind ownership token recorded on the chain. Unlike a coin, no two are interchangeable."
},
mint: {
id: "mint",
cat: "tokens-economics",
term: "Mint / minting",
def: "Creating a brand-new token on the chain and assigning it to an owner, like stamping a fresh serial-numbered certificate into existence."
},
machineNft: {
id: "machineNft",
cat: "tokens-economics",
term: "Machine NFT",
def: "The unique token representing one specific physical machine and its financial profile. It can be sold or bridged on its own, separate from the machine's identity."
},
identityNft: {
id: "identityNft",
cat: "tokens-economics",
term: "Identity NFT",
def: "A non-transferable (soulbound) token minted automatically when a machine registers, representing its identity. Its token ID equals the machine ID."
},
tokenId: {
id: "tokenId",
cat: "tokens-economics",
term: "Token ID",
def: "The unique number identifying one specific token within a collection, like a serial number."
},
mcr: {
id: "mcr",
cat: "tokens-economics",
term: "Machine Credit Rating (MCR)",
def: "A creditworthiness score for a machine (a Moody's-style grade AAA down to NR, plus a 0-100 number) computed from its recorded earnings and activity. Like a credit score for a robot."
},
mcrApi: {
id: "mcrApi",
cat: "tokens-economics",
term: "MCR API",
def: "The public web service you call to fetch a machine's credit score and profile as JSON, and the one place a machine's monetization is switched on or off with a signed message. No login needed: reads are open, and the write is authorized by the signature itself."
},
provisioned: {
id: "provisioned",
cat: "tokens-economics",
term: "Provisioned / NR (Not Rated)",
def: "Early MCR statuses. Provisioned means registered and bonded but with too little history to score yet. NR means no grade, because the score is too low or the machine isn't bonded."
},
event: {
id: "event",
cat: "tokens-economics",
term: "Event (revenue / activity)",
def: "A recorded data point about a machine's work, submitted to the chain to feed its credit score. Revenue events report money earned; activity events report work with no money. NOT a ROS topic message."
},
trustLevel: {
id: "trustLevel",
cat: "tokens-economics",
term: "Trust level",
def: "A label on each submitted event saying how strongly its truth is backed: the machine's word (0), a checkable on-chain record (1), or tamper-proof hardware proof (2)."
},
escrow: {
id: "escrow",
cat: "tokens-economics",
term: "Escrow",
def: "Holding a buyer's payment in a neutral locked place until the service is delivered, then releasing it, so neither side has to trust the other first."
},
paymentRail: {
id: "paymentRail",
cat: "tokens-economics",
term: "Payment rail",
def: "The specific method or channel a payment moves through, like choosing card vs bank transfer vs a particular token."
},
x402: {
id: "x402",
cat: "tokens-economics",
term: "x402",
def: "A web payment standard where a server answers 'payment required' with exact instructions, and the buyer's wallet signs an authorization instead of sending a separate transaction — built for machines and agents paying per request."
},
usdt: {
id: "usdt",
cat: "tokens-economics",
term: "USDT",
def: "A stablecoin token meant to hold a value of one US dollar, used to pay service providers without price swings."
},
fractionalize: {
id: "fractionalize",
cat: "tokens-economics",
term: "Fractionalize (ERC-3643)",
def: "Splitting ownership of one machine into many small tradable shares so multiple people can each own a piece. ERC-3643 is the regulated-securities token standard used to do it."
},
smartContract: {
id: "smartContract",
cat: "smart-contracts",
term: "Smart contract / contract address",
def: "A program deployed on the chain that runs exactly as written and that anyone can call, identified by its own 0x... address."
},
registryContracts: {
id: "registryContracts",
cat: "smart-contracts",
term: "Registry contracts",
def: "On-chain programs that each keep an official, lookup-able list: IdentityRegistry tracks which machines exist, EventRegistry stores their events, IdentityStaking holds their deposits."
},
smartAccount: {
id: "smartAccount",
cat: "smart-contracts",
term: "Smart account (ERC-4337)",
def: "A programmable wallet controlled by code instead of a single key, so it can enforce rules like spending limits. Each machine gets one at activation."
},
submitEvent: {
id: "submitEvent",
cat: "smart-contracts",
term: "submitEvent / batchSubmitEvents",
def: "The calls that record one or many of a machine's revenue or activity entries onto the chain."
},
revert: {
id: "revert",
cat: "smart-contracts",
term: "Revert",
def: "When an on-chain call is rejected and fully undone because a rule was broken, leaving no changes and usually a named error."
},
soulbound: {
id: "soulbound",
cat: "smart-contracts",
term: "Soulbound",
def: "A token that can never be transferred or sold and stays permanently attached to one owner. The Identity NFT is soulbound."
},
bridge: {
id: "bridge",
cat: "cross-chain",
term: "Bridge / bridging",
def: "Moving a token from one chain to another, so the same Machine NFT can exist on a different chain. peaq and Base are live today; bridging is mainnet-only."
},
base: {
id: "base",
cat: "cross-chain",
term: "Base",
def: "Another blockchain network (built by Coinbase) that peaqOS can move Machine NFTs to and from. Paying fees on Base needs Base ETH."
},
omniChain: {
id: "omniChain",
cat: "cross-chain",
term: "Omni-chain / cross-chain",
def: "Working across many separate chains at once, so a machine's identity and credit created on peaq can be read or used on other chains."
},
homeChain: {
id: "homeChain",
cat: "cross-chain",
term: "Home chain",
def: "The chain where a record's canonical, authoritative copy lives. For peaqOS that is peaq chain; every other chain holds a mirror."
},
satelliteChain: {
id: "satelliteChain",
cat: "cross-chain",
term: "Satellite chain",
def: "A chain carrying a read-only, automatically synced mirror of home-chain records, so apps there can use them without crossing back to the home chain."
},
sourceChainId: {
id: "sourceChainId",
cat: "cross-chain",
term: "sourceChainId / sourceTxHash",
def: "Two fields recording which chain an action happened on and its hash there, so a cross-chain event can be traced back and verified."
},
machineAgent: {
id: "machineAgent",
cat: "general-web3",
term: "Machine Agent",
def: "A third-party AI program (Claude, OpenAI, a custom bot) paired to a machine and given limited permission to find, buy, and pay for services on its behalf."
},
delegationPolicy: {
id: "delegationPolicy",
cat: "general-web3",
term: "Delegation policy",
def: "The rules an owner gives an AI agent that cap how much it can spend per transaction and per day and which services it may use, so it transacts within guardrails."
},
machineMarkets: {
id: "machineMarkets",
cat: "general-web3",
term: "Machine Markets / Service Registry",
def: "peaqOS's marketplace where machines list services they offer (Service Registry) and where agents discover, order, pay for, and run services from others."
},
sdk: {
id: "sdk",
cat: "general-web3",
term: "SDK (peaq-os-sdk)",
def: "peaq's code library (Python and JS) you install to call all this functionality without writing low-level blockchain calls yourself."
},
stream: {
id: "stream",
cat: "data-stream",
term: "Stream (Data-as-a-Service)",
def: "The peaqOS function where a machine sells the data it generates: it signs the data, encrypts what's sensitive, and grants buyers access. Selling data, as opposed to selling capacity (that's Monetize)."
},
edgeAgent: {
id: "edgeAgent",
cat: "data-stream",
term: "peaqOS Edge Agent",
def: "Software that runs on the machine itself (as a ROS 2 node) and signs, encrypts, and ships the data it produces. The on-machine half of Stream."
},
dataPackage: {
id: "dataPackage",
cat: "data-stream",
term: "Signed data package",
def: "A bundle of machine data stamped with the machine's identity (DID, timestamp, sequence number) and a signature, so anyone can prove which machine produced it and that it wasn't altered."
},
dataEventMap: {
id: "dataEventMap",
cat: "data-stream",
term: "Data Event Map",
def: "The policy file a machine owner writes to control what streams out: which topics to read, which fields to keep, drop, or encrypt, and where the signed data goes."
},
chunk: {
id: "chunk",
cat: "data-stream",
term: "Chunk",
def: "A bounded, individually encrypted slice of a data stream (by time window or size). The unit a buyer actually purchases and decrypts."
},
chunkChain: {
id: "chunkChain",
cat: "data-stream",
term: "Chunk chain",
def: "A run of chunks linked in order, each referencing the one before it, so missing, reordered, or edited chunks are detectable. Tamper-evidence for a continuous stream."
},
manifest: {
id: "manifest",
cat: "data-stream",
term: "Manifest",
def: "A signed record describing a chunk or dataset — its hashes, storage location, and encryption details — without the data itself. Buyers verify the manifest before trusting or buying."
},
dataset: {
id: "dataset",
cat: "data-stream",
term: "Dataset",
def: "A group of chunks for one topic and time range, packaged for sale with a single fingerprint (a Merkle root) that covers every chunk in it."
},
merkleRoot: {
id: "merkleRoot",
cat: "data-stream",
term: "Merkle root",
def: "One short hash that stands in for a whole set of items, letting you later prove a specific chunk belongs to a dataset without revealing the rest."
},
envelopeEncryption: {
id: "envelopeEncryption",
cat: "data-stream",
term: "Envelope encryption / key wrapping",
def: "Encrypt the data once with a random key, then lock that key separately for each authorized reader. Granting a buyer access re-locks the key to their public key — the data itself is never re-encrypted."
},
accessGrant: {
id: "accessGrant",
cat: "data-stream",
term: "Access grant",
def: "What a buyer receives after paying: the chunk keys they bought, each locked to their public key. They unlock with their private key and decrypt only those chunks."
},
contextProvider: {
id: "contextProvider",
cat: "data-stream",
term: "Context Provider",
def: "A third party that buys machine data, normalizes it into datasets, and serves or resells it (for example, for AI training). The buyer side of Stream, such as DataHive."
},
computeProvider: {
id: "computeProvider",
cat: "monetize",
term: "Compute provider",
def: "A machine that rents out its processing power to a compute network. Instead of sitting idle, the machine runs other people's workloads and earns for it."
},
provisioningManifest: {
id: "provisioningManifest",
cat: "monetize",
term: "Provisioning manifest",
def: "A published, step-by-step install plan that turns a machine into a compute provider: the checks to run first, the commands to execute, and the probes that prove it worked. The machine pulls it on demand and runs it locally."
},
heartbeat: {
id: "heartbeat",
cat: "monetize",
term: "Heartbeat",
def: "A short signed 'I'm here' message a machine sends out at a regular interval. As long as heartbeats keep arriving, the machine counts as online; if they stop, it's marked offline automatically."
},
aggregator: {
id: "aggregator",
cat: "monetize",
term: "Aggregator",
def: "A network that pools capacity from many machines and sells it on, such as a decentralized compute marketplace. Machines connect to an aggregator, which then dispatches work to them."
},
machineWallet: {
id: "machineWallet",
cat: "monetize",
term: "Machine wallet",
def: "The wallet that belongs to the machine itself, separate from its owner's or operator's wallet. Earnings from the machine's work land here by default."
},
walrus: {
id: "walrus",
cat: "chain-infra",
term: "Walrus",
def: "A decentralized storage network where encrypted data chunks can be parked, referenced by walrus:// links. The data stays off the blockchain; only its reference and fingerprint are tracked on-chain."
},
solana: {
id: "solana",
cat: "cross-chain",
term: "Solana",
def: "A high-throughput blockchain. peaqOS wallets can hold a Solana account and sign Solana transactions, and machine-economy payments can settle there."
}
};
Provider provisioning ships in `@peaqos/peaq-os-sdk` 0.5.0+ (JS/TS) and `peaq-os-sdk` 0.5.0+ (Python). It is machine-local: the runner executes entirely on the machine, against no external API.
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.
## 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
```mermaid theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
flowchart LR
Fetch["1. Fetch manifest (versioned, integrity-checked)"] --> Inputs["2. Resolve inputs (types, validation, secrets)"]
Inputs --> Pre["3. Pre-flight gate (block / warn)"]
Pre --> Run["4. Provision (phases + steps)"]
Run --> Verify["5. Verify (success probes)"]
Verify --> Post["6. Post-provision utilities (optional)"]
```
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.
```ts JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
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"
);
```
```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
from peaq_os_sdk import provisioning
manifest = provisioning.fetch_manifest(
"akash", # version defaults to "latest"
repo_base_url=MANIFEST_REPO_URL,
)
print(manifest.resolved_version)
```
* **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:` 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, 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` in manual mode: it is called before each command and returning `False` stops the run resumably, and without the callback the first command step raises `ProvisioningError` (with no resume state; pass `lambda e: True` for an unattended manual run). The JS runner has no confirmation callback at all: `onStep` is informational and cannot decline a step. Use the CLI if you want the interactive gate without building it. Default mode. |
| `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.
```ts JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
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),
});
```
```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
from peaq_os_sdk import provisioning
inputs = provisioning.resolve_inputs(manifest, {
"providerDomain": "provider.example.com",
"walletPassword": "…",
})
executor = provisioning.LocalShellExecutor()
# Python does not run pre-flight for you: run it and pass the result, or the gate never applies.
preflight = provisioning.run_preflight(manifest, executor, mode="auto", inputs=inputs)
preflight.raise_if_blocked()
result = provisioning.provision(
manifest,
inputs,
mode="auto",
preflight=preflight,
executor=executor,
sudo_grant=provisioning.SudoGrant.from_manifest(manifest),
context={"machine_wallet_address": "0x…"},
on_owner_action=prompt_owner,
)
```
**The sudo grant is a scoping and audit aid, not a security boundary.** It reduces the blast radius of an honest manifest, but it cannot contain a hostile one: a granted program can still run arbitrary code through its own arguments. Auto mode elevates commands unattended, so only run a manifest you trust. Verify its integrity (fetch with an expected digest) before an auto run, and prefer OS-level isolation for defense in depth. Treat auto mode on an unverified, remotely served 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 `). |
| `download` | Fetch a resource; integrity is verified via the step's `checksum` (sha256, bare hex or `sha256:`) 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, where `context.machineWallet` is only a legacy alias slated for removal; `{{ 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.
```ts JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
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
});
}
}
```
```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
try:
provisioning.provision(
manifest, inputs, mode="auto", executor=executor,
on_state_change=lambda s: checkpoint.write(s.to_dict()),
)
except provisioning.StepExecutionError as err:
state = err.resume_state # persist this (never contains a secret)
# later:
provisioning.provision(
manifest, inputs, mode="auto", executor=executor,
resume_state=state,
resume_secrets={"wallet_key": "…"}, # 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.
That is automatic inside `provision`, but **not** everywhere. `verifyProvisioning` / `verify_provisioning` (both SDKs) and JS `runPreflight` take their own optional `redaction` registry and do not seed one from your resolved inputs: call them without it and a probe command that interpolates a secret is emitted, executed, and returned unredacted. Python's `run_preflight` does seed redaction from the `inputs` you pass, so hand it your resolved inputs. Pass the registry yourself in the other cases, or run these through the CLI, which seeds it for you.
## 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](/peaqos/functions/monetize): where provisioning fits in the flow
* [Heartbeat SDK reference](/peaqos/sdk-reference/heartbeat): report presence once provisioned
* [Monetization opt-in API](/peaqos/api-reference/put-machine-monetization)