> ## 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.

# Install

> Install peaqOS via npm or pip.

Pick the SDK that matches your stack. Both paths converge on the same onchain state.

## Requirements

| Requirement     | Value                                                                 |
| :-------------- | :-------------------------------------------------------------------- |
| Node.js         | ≥ 22                                                                  |
| TypeScript      | ≥ 5 (for the JS SDK)                                                  |
| Python          | ≥ 3.10 (for the Python SDK)                                           |
| Peer dependency | `viem >= 2.47.10` (JS only; Python pulls `web3 >= 6.0` automatically) |
| RPC access      | peaq mainnet or agung testnet                                         |
| Gas             | Handled by Gas Station on fresh wallets; needs 2FA for request        |

## Install paths

<Tabs>
  <Tab title="Agent skill">
    ### Two pieces

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    # 1. Install the CLI (the skill drives it under the hood)
    pip install peaq-os-cli

    # 2. Add the peaqos skill to your agent (auto-detects Claude Code, Cursor, or Windsurf)
    npx skills add peaqnetwork/peaq-os-skills
    ```

    Then invoke `/peaqos` in any Claude Code session. To target a specific runtime explicitly, add `--agent claude-code | cursor | windsurf`. See the [peaqOS AI page](/peaqos/peaqos-ai) for details and the manual upload path for ChatGPT / custom GPTs.

    ### Works with

    The `peaqos` skill ships first-class adapters for Claude Code, Cursor, and Windsurf — auto-detected, or selected with `--agent`. Hosted assistants without a local CLI (ChatGPT, Claude Projects, custom GPTs) can load `AGENT-PROMPT.md` as a system prompt manually.

    The skill calls the JavaScript and Python SDKs through the CLI. Tabs below apply once you start editing code yourself.
  </Tab>

  <Tab title="CLI">
    ### One command

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    pip install peaq-os-cli

    # Optional: include OWS wallet commands (peaqos wallet create / import / list / …)
    pip install 'peaq-os-cli[ows]'

    peaqos init && peaqos activate --doc-url "https://example.com/docs" --data-api "https://example.com/events"
    ```

    <Warning>
      **After running `peaqos init`, open your `.env` and verify every contract address against the [peaq mainnet contracts](#peaq-mainnet-contracts) table on this page.** A known bug in the init wizard can silently write a contract address to the wrong variable name. If any address is missing or wrong, correct it manually before running `peaqos activate`.
    </Warning>

    Drives the same flows as the SDKs from your terminal: `peaqos init`, `peaqos whoami`, `peaqos activate`, `peaqos qualify event`, `peaqos qualify mcr`, `peaqos show machine`, `peaqos show operator machines`, `peaqos wallet`. See [peaqOS CLI](/peaqos/cli) for the full command reference. CLI and SDK wallet helpers live on [Wallets (OWS)](/peaqos/wallets).
  </Tab>

  <Tab title="JavaScript">
    ### Package

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    npm install @peaqos/peaq-os-sdk viem dotenv
    ```

    OWS wallet helpers (`createWallet`, `importWallet`, `PeaqosClient.fromWallet`, …) work out of the box; `@open-wallet-standard/core` is bundled as a regular dependency of `@peaqos/peaq-os-sdk`. See [Wallets (OWS)](/peaqos/wallets) for the full surface.

    `dotenv` is optional but recommended: `PeaqosClient.fromEnv()` reads from `process.env`, so `import "dotenv/config"` at the top of your entry file is the simplest way to load `.env`.

    ### Language + runtime

    * Node.js ≥ 22
    * TypeScript ≥ 5
    * Package exports both ESM and CJS builds; no bundler workarounds required.

    ### Imports

    ```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    import "dotenv/config";
    import { PeaqosClient } from "@peaqos/peaq-os-sdk";
    ```

    Full method reference on [SDK JS](/peaqos/sdk-reference/sdk-js). Error class hierarchy on [errors](/peaqos/sdk-reference/errors).
  </Tab>

  <Tab title="Python">
    ### Package

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    python3 -m venv .peaq-os
    source .peaq-os/bin/activate

    pip install "peaq-os-sdk>=0.0.2" python-dotenv

    # Optional: include the OWS wallet helpers (createWallet, importWallet, …)
    pip install "peaq-os-sdk[ows]>=0.0.2"
    ```

    `python-dotenv` is optional but recommended: `PeaqosClient.from_env()` reads from dotenv, so `load_dotenv()` at the top of your entry file is the simplest way to load .env.

    ### Language + runtime

    * Python ≥ 3.10
    * `web3.py` pulled in automatically.
    * Virtualenv strongly recommended. The commands above set one up.

    ### Imports

    ```python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    from peaq_os_sdk import PeaqosClient
    ```

    Full method reference on [SDK Python](/peaqos/sdk-reference/sdk-python). Error class hierarchy on [errors](/peaqos/sdk-reference/errors).
  </Tab>

  <Tab title="ROS 2">
    ### Workspace

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git
    cd peaq-robotics-ros2
    ```

    ### Build

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    source /opt/ros/jazzy/setup.bash
    # Docker image: source /opt/ros/humble/setup.bash
    # Native host only: python3 -m pip install -r requirements.txt

    colcon build --packages-select peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
    source install/setup.bash
    ```

    ### Run

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    cp peaq_ros2_examples/config/peaq_robot.example.yaml peaq_ros2_examples/config/peaq_robot.yaml
    # Edit peaq_ros2_examples/config/peaq_robot.yaml and set peaq_os.enabled: true.

    ros2 run peaq_ros2_peaqos peaqos_node --ros-args \
      -p config.yaml_path:=peaq_ros2_examples/config/peaq_robot.yaml
    ```

    Full method mapping on [ROS 2 SDK reference](/peaqos/sdk-reference/ros2/overview). End-to-end commands on [ROS 2 machine runtime](/peaqos/guides/ros2-machine-runtime).
  </Tab>
</Tabs>

## Environment variables

| Variable                          | Required        | Default                 | Purpose                                                                                                                                                                                                                                                                                                                                                 |
| :-------------------------------- | :-------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PEAQOS_RPC_URL`                  | Yes             | n/a                     | peaq chain RPC endpoint                                                                                                                                                                                                                                                                                                                                 |
| `PEAQOS_PRIVATE_KEY`              | Yes             | n/a                     | Owner wallet private key (hex, `0x...`)                                                                                                                                                                                                                                                                                                                 |
| `PEAQOS_NETWORK`                  | CLI only        | n/a                     | `mainnet` or `testnet`. Selects address + URL defaults for the CLI's `peaqos init`. SDK clients ignore it.                                                                                                                                                                                                                                              |
| `PEAQOS_GAS_STATION_URL`          | CLI only        | n/a                     | Faucet base URL. Set to `https://depinstation.peaq.network` for the public peaq-hosted Gas Station. Required for the `peaqos activate` funding step unless `--skip-funding` is set or the wallet already meets the gas threshold.                                                                                                                       |
| `OWS_PASSPHRASE`                  | No              | n/a                     | OWS vault passphrase used by the SDK and CLI wallet helpers (`createWallet`, `importWallet`, `exportWallet`, …). The SDK raises `PeaqosError` if neither this nor the inline `passphrase` arg is set (no interactive prompt). The CLI reads it when `PEAQOS_OWS_WALLET` is set, prompting interactively if unset. See [Wallets (OWS)](/peaqos/wallets). |
| `IDENTITY_REGISTRY_ADDRESS`       | Yes             | n/a                     | Identity Registry contract. See [peaq mainnet contracts](#peaq-mainnet-contracts) for the canonical address.                                                                                                                                                                                                                                            |
| `IDENTITY_STAKING_ADDRESS`        | Yes             | n/a                     | Identity Staking contract                                                                                                                                                                                                                                                                                                                               |
| `EVENT_REGISTRY_ADDRESS`          | Yes             | n/a                     | Event Registry contract                                                                                                                                                                                                                                                                                                                                 |
| `MACHINE_NFT_ADDRESS`             | Yes             | n/a                     | Machine NFT (ONFT) contract                                                                                                                                                                                                                                                                                                                             |
| `DID_REGISTRY_ADDRESS`            | Yes             | n/a                     | DID Registry precompile address (`0x...0800` on every peaq runtime)                                                                                                                                                                                                                                                                                     |
| `BATCH_PRECOMPILE_ADDRESS`        | Yes             | n/a                     | Batch precompile for multi-call bonding (`0x...0805` on every peaq runtime)                                                                                                                                                                                                                                                                             |
| `MACHINE_ACCOUNT_FACTORY_ADDRESS` | No              | n/a                     | `MachineAccountFactory`. Required only for smart-account deploy / predict.                                                                                                                                                                                                                                                                              |
| `MACHINE_NFT_ADAPTER_ADDRESS`     | No              | n/a                     | `MachineNFTAdapter` (LayerZero ONFT adapter). Required only for `bridge_nft` / `bridgeNft` when `source="peaq"`.                                                                                                                                                                                                                                        |
| `PEAQOS_OWS_WALLET`               | CLI only        | n/a                     | Active OWS vault wallet name. When set, the CLI loads the wallet via `OWS_PASSPHRASE` and skips `PEAQOS_PRIVATE_KEY`. Set by `peaqos wallet use` or `peaqos init` (`wallet` path).                                                                                                                                                                      |
| `PEAQOS_MCR_API_URL`              | Set for mainnet | `http://127.0.0.1:8000` | MCR API base URL. The default is for self-hosted dev. Set to `https://mcr.peaq.xyz` to read from the public peaq-hosted MCR.                                                                                                                                                                                                                            |

Full reference with defaults on [SDK JS environment](/peaqos/sdk-reference/sdk-js) and [SDK Python environment](/peaqos/sdk-reference/sdk-python).

## Public RPC endpoints

Use any of the endpoints below for `PEAQOS_RPC_URL`. QuickNode is the primary set; OnFinality and PublicNode are fallbacks. All of them accept EVM JSON-RPC calls. For private dedicated endpoints, see the [QuickNode](https://www.quicknode.com/guides/quicknode-products/how-to-use-the-quicknode-dashboard#create-a-quicknode-endpoint) and [OnFinality](https://documentation.onfinality.io/support/the-enhanced-api-service) guides. Full list on [Connecting to peaq](/peaqchain/build/getting-started/connecting-to-peaq).

<CodeGroup>
  ```bash peaq mainnet theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  https://quicknode1.peaq.xyz
  https://quicknode2.peaq.xyz
  https://quicknode3.peaq.xyz

  # Secondary / fallback
  https://peaq.api.onfinality.io/public
  https://peaq-rpc.publicnode.com
  ```

  ```bash agung testnet theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  https://peaq-agung.api.onfinality.io/public
  https://wss-async-agung.peaq.xyz
  ```
</CodeGroup>

## peaq mainnet contracts

Core contracts are UUPS upgradeable proxies; treat the addresses as the current proxy pointers. For the architecture diagram and what each contract is responsible for, see [Smart contracts](/peaqos/concepts/contracts).

### Required

| Variable                    | Address                                                              |
| :-------------------------- | :------------------------------------------------------------------- |
| `IDENTITY_REGISTRY_ADDRESS` | `0xb53Af985765031936311273599389b5B68aC9956`                         |
| `IDENTITY_STAKING_ADDRESS`  | `0x11c05A650704136786253e8685f56879A202b1C7`                         |
| `EVENT_REGISTRY_ADDRESS`    | `0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA`                         |
| `MACHINE_NFT_ADDRESS`       | `0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9`                         |
| `DID_REGISTRY_ADDRESS`      | `0x0000000000000000000000000000000000000800` (peaq DID precompile)   |
| `BATCH_PRECOMPILE_ADDRESS`  | `0x0000000000000000000000000000000000000805` (peaq batch precompile) |

### Optional

Set only if you use the corresponding SDK method.

| Variable                          | Address                                      | Needed for                                                          |
| :-------------------------------- | :------------------------------------------- | :------------------------------------------------------------------ |
| `MACHINE_ACCOUNT_FACTORY_ADDRESS` | `0x4A808d5A90A2c91739E92C70aF19924e0B3D527f` | `deploySmartAccount` / `getSmartAccountAddress` (ERC-4337)          |
| `MACHINE_NFT_ADAPTER_ADDRESS`     | `0x9AD5408702EC204441A88589B99ADfC2514AFAE6` | `bridgeNft` / `bridge_nft` when `source="peaq"` (LayerZero V2 ONFT) |

## Base mainnet contracts

Needed when bridging **into** peaq from Base. Pass `baseNftAddress` / `base_nft_address` to the bridge method.

| Contract                          | Address                                      |
| :-------------------------------- | :------------------------------------------- |
| `MachineNFTBase` (LayerZero ONFT) | `0xee8A521eA434b11F956E2402beC5eBfa753Babfa` |

## Agung testnet contracts

Use these to point the SDK or CLI at agung. Precompile addresses are identical to mainnet (same fixed slots on every peaq runtime).

### Required

| Variable                    | Address                                                              |
| :-------------------------- | :------------------------------------------------------------------- |
| `IDENTITY_REGISTRY_ADDRESS` | `0x9E9463a65c7B74623b3b6Cdc39F71be7274e5971`                         |
| `IDENTITY_STAKING_ADDRESS`  | `0x55f336714aDb0749DbFE33b057a1702405564E3d`                         |
| `EVENT_REGISTRY_ADDRESS`    | `0x2DAD8905380993940e340C5cE6d313d5c2780040`                         |
| `MACHINE_NFT_ADDRESS`       | `0xB41C2A4f1c19b6B06beaAce0F5CD8439e77C4b1c`                         |
| `DID_REGISTRY_ADDRESS`      | `0x0000000000000000000000000000000000000800` (peaq DID precompile)   |
| `BATCH_PRECOMPILE_ADDRESS`  | `0x0000000000000000000000000000000000000805` (peaq batch precompile) |

### Optional

| Variable                          | Address                                      | Needed for                                                          |
| :-------------------------------- | :------------------------------------------- | :------------------------------------------------------------------ |
| `MACHINE_ACCOUNT_FACTORY_ADDRESS` | `0x65a4DfEB799dFf8CF15f13816d648a7805d6b1F9` | `deploySmartAccount` / `getSmartAccountAddress` (ERC-4337)          |
| `MACHINE_NFT_ADAPTER_ADDRESS`     | `0x63fD7e64A38e50D1486Bc569B4CaCeD38528De22` | `bridgeNft` / `bridge_nft` when `source="peaq"` (LayerZero V2 ONFT) |
| `ADMIN_FLAGS_ADDRESS`             | `0x4181a2Aa34aFb247450FfcBd65be5aBD4Cbee658` | MCR API server (negative-flag + trust-override reads)               |

<Warning>
  **Bridging cannot be exercised on agung.** `MachineNFTAdapter` is deployed, but LayerZero V2 has no DVN routes between agung and Base. `bridgeNft` / `bridge_nft` calls will not relay end-to-end. Test the bridge on peaq mainnet ↔ Base mainnet only.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="INVALID_2FA: OTP code rejected">
    The OTP from your authenticator app was wrong or expired. Generate a fresh code and retry. See full [error code reference](/peaqos/sdk-reference/errors).
  </Accordion>

  <Accordion title="2FA_LOCKED: too many invalid attempts">
    The faucet throttles owners after repeated bad OTPs. Wait out the lockout window and retry. See [error code reference](/peaqos/sdk-reference/errors).
  </Accordion>

  <Accordion title="RATE_LIMITED: faucet rate limit reached">
    The faucet enforces a per-IP and per-wallet cap. Retry after the cooldown. See [error code reference](/peaqos/sdk-reference/errors).
  </Accordion>

  <Accordion title="CAP_EXCEEDED_OWNER: daily owner cap reached">
    The same owner address has hit the daily funding cap. Wait 24 hours or contact support. See [error code reference](/peaqos/sdk-reference/errors).
  </Accordion>

  <Accordion title="Missing PEAQOS_RPC_URL">
    Set `PEAQOS_RPC_URL` in your environment to a valid peaq chain RPC endpoint (e.g., `https://peaq.api.onfinality.io/public`). Without it, `PeaqosClient.fromEnv()` raises a `ValidationError`. See [Public RPC endpoints](#public-rpc-endpoints) for the full list. Full error taxonomy on [errors](/peaqos/sdk-reference/errors).
  </Accordion>
</AccordionGroup>