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

# Quickstart

> Register your first machine in five minutes.

Install the SDK, generate a keypair, register a machine.

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="Agent skill">
        ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
        pip install peaq-os-cli
        npx skills add peaqnetwork/peaq-os-skills
        ```

        Auto-detects Claude Code, Cursor, or Windsurf. Invoke `/peaqos` in Claude Code and it drives the whole flow below. To target a specific runtime, add `--agent claude-code | cursor | windsurf` — see the [peaqOS AI page](/peaqos/peaqos-ai).
      </Tab>

      <Tab title="CLI">
        ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
        pip install peaq-os-cli
        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 [mainnet contracts table](/peaqos/install#peaq-mainnet-contracts). A known bug in the init wizard can silently write an address to the wrong variable name — correct any mismatches before running `peaqos activate`.
        </Warning>

        Wraps the SDK into terminal commands. Full reference on the [peaqOS CLI page](/peaqos/cli).
      </Tab>

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

      <Tab title="pip">
        ```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 python-dotenv
        ```
      </Tab>

      <Tab title="ROS 2">
        ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
        git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git
        cd peaq-robotics-ros2
        source /opt/ros/jazzy/setup.bash
        colcon build --packages-select \
          peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
        source install/setup.bash
        ```

        Wraps the SDKs as ROS 2 services. Full reference on [SDK: ROS 2](/peaqos/sdk-reference/ros2/overview).
      </Tab>
    </Tabs>

    Full install reference on the [install page](/peaqos/install).
  </Step>

  <Step title="Configure">
    Create a `.env` file:

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    # peaq mainnet RPC. See /peaqos/install#public-rpc-endpoints for alternatives.
    PEAQOS_RPC_URL=https://peaq.api.onfinality.io/public
    PEAQOS_PRIVATE_KEY=0x...

    # Mainnet contracts auto-populated by fromEnv(); shown here for reference. Override only for custom deploys.
    # For agung testnet addresses see /peaqos/install#agung-testnet-contracts.
    IDENTITY_REGISTRY_ADDRESS=0xb53Af985765031936311273599389b5B68aC9956
    IDENTITY_STAKING_ADDRESS=0x11c05A650704136786253e8685f56879A202b1C7
    EVENT_REGISTRY_ADDRESS=0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA
    MACHINE_NFT_ADDRESS=0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9
    DID_REGISTRY_ADDRESS=0x0000000000000000000000000000000000000800
    BATCH_PRECOMPILE_ADDRESS=0x0000000000000000000000000000000000000805

    # Optional. Defaults to http://127.0.0.1:8000
    PEAQOS_MCR_API_URL=https://mcr.peaq.xyz
    ```

    Mainnet contract addresses (identity, staking, event, NFT, DID, batch) populate automatically with `PeaqosClient.fromEnv()`, so you don't need to set them manually. See the [environment variables table](/peaqos/install#environment-variables) for the full list and the [public RPC endpoints](/peaqos/install#public-rpc-endpoints) section for QuickNode primary plus OnFinality/PublicNode fallbacks.
  </Step>

  <Step title="Register">
    <CodeGroup>
      ```typescript JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
      import "dotenv/config";
      import { PeaqosClient } from "@peaqos/peaq-os-sdk";

      const client = PeaqosClient.fromEnv();

      // Register the client's own wallet as a new machine.
      // The call sends the minimum bond (1 PEAQ) with the transaction.
      const machineId = await client.registerMachine();

      console.log("Registered machine ID:", machineId);
      ```

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

      load_dotenv() # load envs from .env file

      client = PeaqosClient.from_env()

      # Register the client's own wallet as a new machine.
      # The call sends the minimum bond (1 PEAQ) with the transaction.
      machine_id = client.register_machine()

      print("Registered machine ID:", machine_id)
      ```
    </CodeGroup>

    Proxy operators register machines on behalf of another wallet. See the [self-managed](/peaqos/guides/self-managed-onboarding) and [proxy operator](/peaqos/guides/proxy-operator-fleet) guides for the fleet flow with `registerFor`.
  </Step>
</Steps>

<Accordion title="What just happened">
  * `PeaqosClient.fromEnv()` bound the signing key from `PEAQOS_PRIVATE_KEY` and loaded contract addresses from the environment.
  * `registerMachine` sent 1 PEAQ as `msg.value`, registered the identity in IdentityRegistry, and returned the newly assigned machine ID.
  * The machine ID is the handle for every downstream call: minting the Machine NFT (`mintNft`), writing DID attributes, submitting events, and MCR queries.
</Accordion>

## Next

<CardGroup cols={2}>
  <Card title="Self-managed onboarding" icon="user" href="/peaqos/guides/self-managed-onboarding">
    Owner = operator. One machine, one wallet.
  </Card>

  <Card title="Proxy operator fleet" icon="layer-group" href="/peaqos/guides/proxy-operator-fleet">
    One owner, many machines, `registerFor`.
  </Card>
</CardGroup>