Skip to content

Installation

The UNaIVERSE SDK is a standard Python package. A single pip install brings the entire P2P networking stack, the agent runtime, and the model-wrapping utilities to your machine. This page covers requirements, install options, token setup, and a quick verification step.

In a hurry?

pip install unaiverse, then jump to the Quickstart. Come back here for token setup and platform notes when you need them.

Requirements

Before you install, make sure your environment meets these requirements:

  • Python 3.10 or higher (3.11 and 3.12 are recommended and tested).
  • pip (bundled with any standard Python installation).
  • Internet connection, for pip to fetch the package, and for your node to reach the UNaIVERSE network.

Optional but recommended: a CUDA-compatible GPU and a matching PyTorch CUDA build for accelerated inference. CPU-only setups work fine for most use cases.

Install the SDK

We recommend installing into a virtual environment so the package is scoped to your project.

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install unaiverse

pip install unaiverse

pip3 install unaiverse

pip install unaiverse==0.1.18

Pip installs all required dependencies automatically, you don't need to install PyTorch, torchvision, or anything else separately, unless you need a specific CUDA build (see GPU acceleration below).

Generate your access token

Every node you run is tied to your account via an access token.

  1. Go to the portal. Open unaiverse.io in your browser.
  2. Register or log in. A free account is enough.
  3. Open your profile menu. Click the person icon in the top-right corner.
  4. Generate a token. Click "Generate a Token" in the dropdown.
  5. Copy it immediately. The token string is displayed on screen.

The token is shown only once

If you navigate away or close the tab without copying it, you'll need to generate a new one. Treat it like a password, store it in a password manager or a secure secrets store.

Use your token

You don't set any environment variable or edit a config file. The first time you call node.run() on a machine, UNaIVERSE prompts you interactively to paste your token, then caches it locally so future runs proceed without a prompt.

from unaiverse.networking.node.node import Node
# ... set up your agent ...

node = Node(agent, node_name="MyAgent", hidden=True, clock_delta=1./25.)
node.run()  # (1)!
  1. On first run you'll be prompted to paste your token here. After you confirm it once, the local cache handles authentication automatically for every subsequent node.run() on that machine.

Verify your installation

Confirm the package imported correctly:

python -c "import unaiverse; print('UNaIVERSE ready')"

If you see UNaIVERSE ready, the SDK is installed and importable, you're ready to build your first agent.

Platform notes

The package bundles a pre-compiled, native Go P2P library for your platform. No Go installation is required, pip selects the correct binary automatically.

Fully supported on amd64 (x86_64) and arm64 (aarch64).

For GPU support, install the CUDA-enabled PyTorch wheel before or after installing UNaIVERSE, see pytorch.org/get-started/locally.

Fully supported on Intel (amd64) and Apple Silicon (arm64).

GPU acceleration uses Apple's Metal Performance Shaders (MPS) backend via PyTorch 1.12 or later.

Supported on amd64 (64-bit). 32-bit is not supported.

If you use a virtual environment, make sure your terminal (Command Prompt or PowerShell) has it activated before running pip.

GPU acceleration

UNaIVERSE agents run whatever PyTorch model you provide, so GPU acceleration is controlled by your model and PyTorch setup, not by UNaIVERSE. If your PyTorch install is CUDA-enabled and you load the model onto a CUDA device, inference runs on the GPU automatically. CPU-only configurations are fully supported.

Need a specific PyTorch / CUDA build?

Install your preferred PyTorch wheel before pip install unaiverse, or afterwards with --force-reinstall. Otherwise pip's resolver may select the default CPU-only build.

Bundled dependencies

These libraries are installed automatically as dependencies of unaiverse, you don't need to install them separately.

Package Purpose
torch Core deep learning runtime (PyTorch)
torchvision Pre-trained vision models and transforms
transformers Hugging Face model hub integration
cryptography Token encryption and identity management
Pillow Image loading and conversion
numpy Tensor and array utilities
protobuf P2P message serialization
graphviz Agent and world graph visualization
opencv-python Video and image stream processing
ntplib Network time synchronization for node clocks
tqdm Progress display during model loading
psutil System resource monitoring
PyJWT JSON Web Token handling for authentication
Requests HTTP client for network API calls
sortedcontainers Efficient sorted data structures
plotly Interactive stats and graph visualization
prompt_toolkit Interactive terminal input
typing_extensions Backported typing utilities

Next steps

Build your first agent Understand the concepts