QUBES

Setup Guide

Everything you need to get your Qubes AI companion up and running. Follow these steps to configure API keys and unlock the full potential of your sovereign AI.

🎬 Watch: Creating Your First Qube

See the entire Qube creation process from start to finish in this short walkthrough.

Creating a Qube, minting its NFT identity, and having your first conversation

⚡ Quick Start

Get up and running in minutes with the minimum required setup.

Minimum Requirements

To use Qubes, you need:

  • CashTokens Wallet Required - To receive your Qube's NFT identity (we recommend Electron Cash)
  • Pinata IPFS Required - For storing your Qube's metadata on IPFS (free tier available)
  • At least one AI provider - Either a cloud API key OR Ollama (free and bundled with Qubes!)

That's it! Everything else is optional and can be added later.

Qubes Settings Panel

Settings panel where you'll enter your API keys

💰 Bitcoin Cash Wallet Required for Minting

To mint your Qube as an NFT on Bitcoin Cash, you need a wallet that supports CashTokens to receive and store the NFT. We recommend Electron Cash - it's free, open-source, and fully supports the CashTokens protocol.

Why Do I Need a CashTokens Wallet?

When you create a Qube, its identity is minted as an NFT (CashToken) on Bitcoin Cash. This NFT is your Qube's permanent, verifiable identity. You need a CashTokens-compatible wallet to:

  • Receive the NFT - The minted Qube NFT is sent to your wallet
  • True ownership - You hold the private keys, not a company
  • Transferability - Send your Qube to another wallet or person
  • Verification - Anyone can verify your Qube's identity on-chain
  • Permanence - Your Qube exists as long as Bitcoin Cash exists

💡 Important: Payment vs. Storage

You don't need BCH in your Electron Cash wallet to mint. The minting payment can be sent from any wallet - an exchange, a mobile wallet, or anywhere else you hold BCH.

You only need Electron Cash (or another CashTokens wallet) to receive and store the NFT that represents your Qube's identity.

Step 1: Download Electron Cash

  1. Go to the official Electron Cash website
    electroncash.org
  2. Download the version for your operating system
    Available for Windows, macOS, Linux, and Android.
  3. Install and launch Electron Cash
    Follow the standard installation process for your OS.

Step 2: Create a New Wallet

  1. Select "Create a new wallet"
    When Electron Cash launches for the first time, choose to create a new wallet.
  2. Choose "Standard wallet"
    This is the default option and works perfectly for Qubes.
  3. Select "Create a new seed"
    This generates a new set of private keys for your wallet.
  4. Write down your seed phrase!
    ⚠ CRITICAL: Back up your seed phrase!

    Write down the 12 words on paper and store them safely. This is the ONLY way to recover your wallet (and your Qubes) if something goes wrong. Never share these words with anyone!

  5. Confirm your seed phrase
    Electron Cash will ask you to re-enter some words to verify you wrote them down.
  6. Set a password (optional but recommended)
    This encrypts your wallet file on your computer.
Electron Cash seed phrase backup

The seed phrase screen - write these 12 words down on paper and store safely!

Step 3: Get Your Public Key

When creating a Qube, you'll need to provide your compressed public key from Electron Cash. The Qubes app automatically derives your token-aware address from this key.

🔑 Finding Your Public Key in Electron Cash

  1. In Electron Cash, go to the "Addresses" tab
  2. Right-click on any address you want to use
  3. Select "Details..."
  4. Look for the "Public keys:" field (66 hex characters starting with 02 or 03)
  5. Click the copy button next to the public key - you'll paste this when creating your Qube
Electron Cash Addresses tab

Step 1: Go to the Addresses tab and select an address

Right-click menu showing Details option

Step 2: Right-click the address and select "Details..."

Address Details showing Public Key

Step 3: Copy the Public Key (starts with 02 or 03, 66 characters total)

Why Public Key Instead of Address?

Providing your public key (instead of just an address) enables two important features:

  • NFT Delivery: Your token-aware (z...) address is derived automatically for receiving the Qube NFT
  • Qube Wallet: Each Qube gets its own P2SH multi-sig wallet where you and the Qube jointly control funds

Understanding Qube Wallets

Each Qube has its own BCH wallet - a special P2SH (Pay-to-Script-Hash) address that enables asymmetric control:

💰 Your Qube's Personal Wallet

  • Owner alone: You can withdraw funds anytime (emergency/full control)
  • Owner + Qube together: Normal operations where the Qube proposes transactions and you approve
  • Auto-Send Whitelist: You can whitelist other Qubes' wallets so your Qube can send BCH to them without approval

This means your Qube can receive tips, earn BCH, and manage its own funds - while you always retain ultimate control. The wallet address starts with bitcoincash:p... (P2SH format).

Tip: Access wallet security settings (store private key, manage whitelist) via the "Private Key" button on the Blockchain face of your Qube's card.

Address Types in Qubes

Prefix Type Purpose
bitcoincash:q... Standard (P2PKH) Your personal BCH address
bitcoincash:z... Token-aware Where your Qube's NFT is sent (derived from your pubkey)
bitcoincash:p... P2SH (Multi-sig) Your Qube's personal wallet (owner + Qube control)
Electron Cash Receive tab showing q and z addresses

The Receive tab shows both your standard (q...) and token-aware (z...) addresses

Minting Cost

When you mint your Qube, you'll pay a small minting fee. This can be sent from any wallet - exchange, mobile wallet, or another BCH wallet you already have.

One-Time Minting Fee

0.01 BCH ≈ $5 USD
(Early adopter pricing - normally 0.1 BCH)

This is a one-time fee. Once minted, your Qube is yours forever with no ongoing costs.

Where to Get BCH (If You Don't Have Any)

🏦 Exchanges

Buy BCH on popular exchanges:

🔁 Swap Services

Swap other crypto for BCH:

🤝 Peer-to-Peer

Buy directly from people:

🎉 Ready to Mint!

Once you have your Electron Cash wallet set up and know how to find your public key, you're ready to mint your Qube! During the creation process in the Qubes app:

  1. You'll enter your compressed public key (66 hex chars starting with 02 or 03)
  2. Qubes automatically derives your token-aware (z...) address for the NFT
  3. You'll pay the minting fee from any wallet (exchange, mobile, etc.)
  4. Your Qube's NFT is minted and sent to your derived z-address
  5. Your Qube also gets its own P2SH wallet for receiving funds!

The Qubes app will guide you through each step of this process.

🌐 Pinata IPFS Setup Required

Pinata stores your Qube's identity and metadata on IPFS (InterPlanetary File System). This ensures your Qube's identity is permanent and verifiable on the blockchain.

⚠ Important

Pinata is required to create a Qube. Your Qube's avatar and metadata are stored on IPFS, which requires a Pinata API key. The free tier is sufficient for most users.

Step-by-Step Instructions

  1. Create a free Pinata account
    Go to app.pinata.cloud/register and sign up.
    The free tier includes 1GB storage - more than enough for Qube metadata.
  2. Navigate to API Keys
    Once logged in, go to Developers → API Keys
  3. Create a new key
    Click the "+ New Key" button in the top right corner.
  4. Configure the key
    Name it anything you like (e.g., "Qubes"). Default permissions are fine - no need to change anything.
  5. Copy the JWT immediately!
    After clicking "Create", you'll see your JWT token. It starts with eyJ...
    ⚠ This JWT is only shown ONCE! Copy it before closing the dialog. You cannot retrieve it later - you'd have to create a new key.
  6. Enter in Qubes
    Open Qubes → Settings → API Keys → Paste into the Pinata field → Save

🤖 AI Providers

Qubes supports multiple AI providers. You only need one to get started, but you can add as many as you like and switch between them anytime.

API Keys Panel in Qubes Settings

The API Keys panel showing all available providers with Test and Save buttons

For Each Provider

  • Input field - Paste your API key (masked for security)
  • Test button - Verify your key works before saving
  • Save button - Store the key (encrypted with your master password)
  • Delete link - Remove a saved key
  • Green checkmark - Indicates the key is configured and saved

🎯 OpenAI

GPT-4o, GPT-4, o1, o3-mini, DALL-E

  1. Go to platform.openai.com/api-keys
  2. Sign in or create an account
  3. Click "Create new secret key"
  4. Copy the key and add billing
sk-...

🧠 Anthropic

Claude Opus 4, Claude Sonnet 4

  1. Go to console.anthropic.com/settings/keys
  2. Sign in or create an account
  3. Click "Create Key"
  4. Copy the key and add billing
sk-ant-...

🎨 Google AI

Gemini 2.5 Pro, Gemini 2.5 Flash

  1. Go to aistudio.google.com/app/apikey
  2. Sign in with your Google account
  3. Click "Create API Key"
  4. Choose or create a project
AIza...

🔭 DeepSeek

DeepSeek R1, DeepSeek V3

  1. Go to platform.deepseek.com/api_keys
  2. Sign in or create an account
  3. Create new API key
  4. Add credits to your account
sk-...

🔎 Perplexity

Sonar Pro, Sonar Deep Research

  1. Go to perplexity.ai/settings/api
  2. Sign in or create an account
  3. Generate an API key
  4. Copy the key
pplx-...

🏥 Venice

Private AI (Uncensored)

  1. Go to venice.ai/settings/api
  2. Sign in or create an account
  3. Generate an API key
  4. Copy the key
varies

⚡ NanoGPT

Pay-per-prompt with crypto

  1. Go to nano-gpt.com/api
  2. Sign in or create an account
  3. Generate an API key
  4. Fund with cryptocurrency
varies

🎤 Google Cloud TTS Optional

Google Cloud Text-to-Speech provides access to 380+ premium voices in multiple languages. This requires more setup than other providers but offers the best voice quality and variety.

What You'll Get

  • 380+ voices across 40+ languages
  • Neural2 and Studio quality voices
  • Free tier: 1 million characters/month for Neural2
  • Significantly better quality than basic TTS

Step 1: Create a Google Cloud Project

  1. Go to console.cloud.google.com
  2. Click "Select a project" in the top bar, then "New Project"
  3. Name your project (e.g., "Qubes TTS")
  4. Click "Create" and wait for it to be ready

Step 2: Enable the Text-to-Speech API

  1. Go to Text-to-Speech API page
  2. Make sure your new project is selected
  3. Click the blue "Enable" button

Step 3: Create a Service Account

  1. Go to IAM & Admin → Service Accounts
  2. Select your project if prompted
  3. Click "Create Service Account"
  4. Name it something like qubes-tts
  5. Click "Create and Continue"
  6. For role, you can select "Cloud Text-to-Speech User" or just skip this step
  7. Click "Done"

Step 4: Download the JSON Key

  1. Click on your newly created service account
  2. Go to the "Keys" tab
  3. Click "Add Key" → "Create new key"
  4. Select JSON format
  5. Click "Create"
  6. A JSON file will download - save this somewhere safe!

⚠ Save This File Securely

The downloaded file will have a name like:

gen-lang-client-1234567890-abc123def456.json

Save it to a permanent location you'll remember. You can rename it if you prefer:

C:\Users\YourName\qubes-tts-key.json

Or keep the original name - just remember where you saved it!

Step 5: Configure in Qubes

  1. Open Qubes and go to Settings
  2. Expand the "Google Cloud TTS" panel
  3. Enter the full path to your JSON key file
  4. Click "Save Path"
Google Cloud TTS Settings Panel

The Google Cloud TTS panel - enter the full path to your JSON credentials file

Example Paths

Windows:

C:/Users/YourName/qubes-tts-key.json

Mac:

/Users/yourname/qubes-tts-key.json

Linux:

/home/yourname/qubes-tts-key.json

Note: Use forward slashes (/) even on Windows, or escape backslashes (\\).

🗣 Other Voice Providers Optional

In addition to Google Cloud TTS, Qubes supports these voice providers:

🎧 OpenAI TTS

tts-1, tts-1-hd (6 voices)

Uses your existing OpenAI API key. No additional setup required if you already have OpenAI configured.

Voices: alloy, echo, fable, onyx, nova, shimmer

🎨 Google Gemini TTS

Gemini 2.5 Flash TTS voices

Uses your existing Google AI API key. No additional setup required if you already have Google AI configured.

Provides high-quality voices through the Gemini API.

🎙 ElevenLabs

Premium voice cloning & synthesis

  1. Go to elevenlabs.io
  2. Sign in or create an account
  3. Go to Profile → API Key
  4. Copy your API key

🎤 Deepgram

Speech-to-Text (STT)

  1. Go to deepgram.com
  2. Sign in or create an account
  3. Dashboard → API Keys
  4. Create and copy the key

🤖 Local AI with Ollama Free

Want to run AI 100% locally without sending data to the cloud? Ollama is bundled with Qubes and lets you run open-source models on your own hardware.

Benefits of Local AI

  • Free - No API costs, ever
  • Private - Data never leaves your computer
  • Offline - Works without internet
  • Uncensored - No content filtering

Getting Started

Ollama is already bundled with Qubes! On first launch, Qubes will check if Ollama is running. If not, you can start it from the setup wizard.

Downloading Models

The first time you use a local model, Ollama will download it automatically. Popular models include:

Model Size Best For
llama3.2 ~2GB General chat, fast responses
mistral ~4GB Balanced quality and speed
codellama ~4GB Programming and code
llama3.1:70b ~40GB Best quality (needs lots of RAM)

Manual Model Download

To download a model manually, open a terminal and run:

ollama pull llama3.2

Replace llama3.2 with any model name from ollama.com/library.

Hardware Requirements

  • Minimum: 8GB RAM for small models (llama3.2)
  • Recommended: 16GB RAM for medium models (mistral, codellama)
  • Large models: 32GB+ RAM or GPU with sufficient VRAM

🏠 Dashboard Overview

Once you've created your Qubes, the Dashboard is your command center for managing them all.

Qubes Dashboard

The Dashboard showing three Qubes, each displaying a different card face

Qube Cards

Each Qube is displayed as an interactive card with three faces you can flip between:

👤 Front Face

The default view showing:

  • Avatar and name
  • Qube ID (8-character hex)
  • AI model and voice
  • Creator and block count
  • Chat, Reset, Delete buttons

Top-right corner: TTS toggle button (turn voice on/off)

⛓ Blockchain Face

Flip to see blockchain data:

  • NFT, BCH, QUBE balances
  • Wallet addresses (P2SH, q, z)
  • NFT category and mint TX
  • IPFS links
  • Private Key button - opens wallet security modal

The Private Key modal lets you store your owner key and manage the auto-send whitelist for other Qubes.

🎵 Audio Visualizer Face

Customize the voice waveform:

  • 11 waveform styles (F1-F11)
  • Color themes and gradients
  • Sensitivity adjustment
  • Bluetooth audio offset
  • Multiple monitor output

Top-right corner: Visualizer toggle (or press V key)

Top Toolbar

  • Grid / List toggle - Switch between card and list views
  • Search - Filter Qubes by name
  • Import from Wallet - Import a Qube using its NFT
  • Sync to IPFS - Backup Qube data to IPFS
  • Transfer - Transfer Qube ownership
  • + Create New Qube - Launch the creation wizard

Left Sidebar (Qube Roster)

Quick access to all your Qubes showing avatar, name, current AI model, and a blockchain badge (green checkmark) if minted as an NFT.

🎉 You're Ready!

With your API keys configured, you're ready to create your first Qube. Launch the app, follow the creation wizard, and meet your new AI companion!

Get Qubes Learn More
Qubes Dashboard

Your Qubes Dashboard - where your AI companions live