Atho logo Atho The Platinum Standard Of The Quantum Age
Join Atho Quick Node Setup

From fresh clone to active node in minutes.

This page walks through setup, API auth, Falcon/Kyber checks, key creation and management, node launch, and verification. It follows the current Atho quickstart runbook and adds a dedicated key-manager flow for GUI and CLI operators.

Network notice: Run on testnet until mainnet launch. Set ATHO_NETWORK=testnet before starting nodes.

Start Setup Open Full Docs

Before you start

  • Testnet-only until mainnet launch Keep ATHO_NETWORK=testnet aligned across GUI, CLI, and node startup commands.
  • Python + venv Python 3.9+ with an isolated virtual environment is required.
  • API key is mandatory Node and CLI actions require API auth headers and permissions.
  • Falcon/Kyber runtime checks + key setup Install/register cryptographic binaries, then run key manager to create wallet keys before routine node operations.
Setup Steps

Join flow by operating system

Linux Setup

Clone repo, create virtual environment, install dependencies, then launch nodes.

git clone <repo-url>
cd <repo-dir>
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
./.venv/bin/python Src/Api/auth.py
./.venv/bin/python Src/Falcon/Falcon/install_platform_binary.py
./.venv/bin/python Src/GUI/cliui.py
# CLI: wallet new 24
./.venv/bin/python Src/Main/runnode.py
Linux

macOS Setup

Use the same core flow as Linux with local build toolchain available for native dependencies.

git clone <repo-url>
cd <repo-dir>
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
./.venv/bin/python Src/Api/auth.py
./.venv/bin/python Src/Falcon/Falcon/install_platform_binary.py
./.venv/bin/python Src/GUI/cliui.py
# CLI: wallet new 24
./.venv/bin/python Src/Main/runnode.py
macOS

Windows Setup (PowerShell)

Install compiler/build tools first, then run the setup sequence below.

git clone <repo-url>
cd <repo-dir>
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
python Src/Api/auth.py
python Src/Falcon/Falcon/install_platform_binary.py
python Src/GUI/cliui.py
# CLI: wallet new 24
python Src/Main/runnode.py
Windows

API Auth + Validation

Create credentials once, then verify API chain status before routine operation.

curl -H "X-API-Key:<KEY>" \
  -H "X-User:<USER>" \
  -H "X-Pass:<PASS>" \
  http://127.0.0.1:<full_api_port>/chain/info
Validation

Troubleshooting First Path

Use troubleshooting docs for startup/auth/sync issues before deeper recovery actions.

Open Troubleshooting Docs
Recovery
Key Management

After venv + Falcon build, run key manager before normal wallet/miner use.

This is the required step between dependency setup and ongoing node operation. Create or import keys first, then confirm defaults and wallet security policy so send/mining flows have valid signing material.

Recommended order (fast path)

  1. Finish venv, dependencies, API key setup, and Falcon binary install.
  2. Open CLI wallet/key manager and generate a mnemonic-backed key (default 24 words).
  3. Confirm addresses/default key, then start nodes and verify API health.
source .venv/bin/activate
./.venv/bin/python Src/GUI/cliui.py
# in CLI:
wallet new 24
wallet addresses
wallet balance
Run Order

Manage keys in GUI or CLI

Use GUI Wallet tab for visual control, or CLI tools for operator scripting and precision changes.

./.venv/bin/python Src/Accounts/change_default_key.py list
./.venv/bin/python Src/Accounts/change_default_key.py set-default --network testnet --id miner_1
./.venv/bin/python Src/Accounts/change_default_key.py rename --network testnet --old miner_1 --new validator_main
./.venv/bin/python Src/Accounts/change_default_key.py import --network testnet --id import_1 --file /path/to/key.txt
./.venv/bin/python Src/Accounts/change_default_key.py delete --network testnet --key import_1
GUI + CLI

Key manager / wallet features

  • Create, recover, import, export Mnemonic-backed keys (12/24/48 words), deterministic recovery, and wallet import/export support.
  • Rename, delete, set default Manage active wallet identities per network (`mainnet`, `testnet`, `regnet`) with safe default handling.
  • Wallet lockbox security Password + AES-256-GCM with Kyber-backed unlock workflow, lock/unlock, password change, and encrypted backup/export controls.
Security + Control

Runtime signals to watch

  • Peer handshake Look for `handshake_ok` and connected peers in network logs.
  • Sync progression Tip height should move toward network best known chain.
  • Node process health Use `stop.py --active` to verify running node PIDs and detect stale starts.

Fast troubleshooting shortcuts

  • List active nodes ./.venv/bin/python Src/Main/stop.py --active
  • Stop stale background nodes ./.venv/bin/python Src/Main/stop.py --all
  • Deep fixes Use the full troubleshooting runbook for API, sync, storage, and miner-specific recovery paths.
Search Full Documentation

Most common errors and direct doc buttons

These are the high-frequency setup failures. Each one includes a direct documentation button so users can jump straight to the exact fix path.

API key not set / auth headers missing

Symptoms: 401/403 responses or GUI wallet calls failing auth.

./.venv/bin/python Src/Api/auth.py
API Auth Doc Troubleshooting

Virtual environment not set/activated

Symptoms: import errors, wrong python path, package mismatch across runs.

python3 -m venv .venv
source .venv/bin/activate
Quickstart Doc Dependency Fixes

Requirements not fully installed

Symptoms: missing modules after install (`lmdb`, `cryptography`, GUI/runtime deps).

python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
Install Sequence Install Errors

Outdated pip / installer toolchain

Symptoms: wheel build failures or package resolver issues during setup.

python -m pip install --upgrade pip setuptools wheel
Quickstart Install

Falcon binary not installed/registered

Symptoms: runtime signing checks fail because expected binary is missing or stale.

./.venv/bin/python Src/Falcon/Falcon/install_platform_binary.py
Binaries Doc Falcon Reference

Binary hash pin mismatch (manual update)

Symptoms: startup blocks with pinning/runtime-guard digest mismatch messages.

# update expected Falcon digest pins in:
Src/Utility/const.py
Pinning Guide Binary Workflow

Wrong network mode (must stay on testnet)

Symptoms: no headers, peers on a different chain, sync mismatch.

export ATHO_NETWORK=testnet
./.venv/bin/python Src/Main/runnode.py
Network Setup Sync Issues

Stale node processes / port conflicts

Symptoms: nodes fail to start or report that ports are already in use.

./.venv/bin/python Src/Main/stop.py --active
./.venv/bin/python Src/Main/stop.py --all
Node Stop Doc Port Fixes