Build Coldstar

Everything you need to install, build from source, or deploy to an air-gapped machine.

Prerequisites

Coldstar has two required dependencies and one optional one:

Python Dependencies

These are installed automatically via pip install -r local_requirements.txt:

• rich & questionary — Powers the terminal UI (menus, colors, progress bars)
• solana & solders — Talks to the Solana network and builds transactions
• pynacl — Fallback signer if Rust isn't installed (Ed25519 in Python)
• argon2-cffi — Derives encryption keys from your passphrase (memory-hard, brute-force resistant)
• httpx — Makes RPC calls to Solana validators

Quick Install

Get up and running in four commands. Pick your platform:

# Clone the repository
git clone https://github.com/devsyrem/coldstar.git
cd coldstar

# Install Rust and Python (if not already installed)
brew install rust
brew install python

# Install dependencies
pip3 install -r local_requirements.txt

# Launch Coldstar
python3 main.py

# Clone the repository
git clone https://github.com/devsyrem/coldstar.git
cd coldstar

# Install Rust and Python (if not already installed)
winget install Rustlang.Rustup
winget install Python.Python.3.11

# Install dependencies
pip install -r local_requirements.txt

# Launch Coldstar
python main.py

# Clone the repository
git clone https://github.com/devsyrem/coldstar.git
cd coldstar

# Install Rust and Python (Debian/Ubuntu)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
sudo apt install python3 python3-pip

# Install dependencies
pip3 install -r local_requirements.txt

# Launch Coldstar
python3 main.py

Build from Source (Manual)

If you want more control over the setup — for example, using a virtual environment or building the Rust signer yourself — follow these steps:

git clone https://github.com/devsyrem/coldstar
cd coldstar

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r local_requirements.txt

cd secure_signer
cargo build --release
cd ..

# Interactive chain picker (Solana or Base)
python main.py

# Or launch directly into a specific chain
python main.py --solana
python main.py --base

Rust Secure Signer

This is the security-critical component of Coldstar. The Rust signer handles all private key operations in isolated, locked memory — your key never touches Python, never gets swapped to disk, and is wiped even if the process crashes. It's a standalone Rust crate (coldstar_secure_signer v1.1.0).

Build the Signer

cd secure_signer

# Build release binary + shared library
cargo build --release

# Run tests
cargo test

This produces two files:

• target/release/coldstar-signer — Standalone CLI you can use to sign transactions directly
• target/release/libcoldstar_secure_signer.{so,dylib} — Shared library that Python loads automatically via FFI

What each Rust file does

Release Profile

The release build is optimized for both speed and small binary size:

• LTO — Link-time optimization merges all code into one unit for maximum dead-code elimination
• codegen-units = 1 — Trades compile time for better runtime performance
• panic = abort — No unwinding overhead, smaller binary (zeroization still happens via Drop)

Docker

If you don't want to install Python and Rust on your host machine, run Coldstar in a container. The included Dockerfile sets up everything automatically.

# Build the Docker image
docker build -t coldstar .

# Run interactively
docker run -it --rm coldstar

USB Device Passthrough (Linux only)

Coldstar needs access to your USB drive. On Linux, pass the device directly into the container:

docker run -it --rm \
    --privileged \
    --device=/dev/sdb:/dev/sdb \
    coldstar

Project Structure

Here's how the codebase is organized. The Python layer handles the UI, wallet management, and network calls. The Rust layer handles all private key operations.

Configuration

All settings live in config.py. You can edit this file to change RPC endpoints, directory paths, or the default chain. No environment variables or external config files needed.

Air-Gapped Setup

For maximum security, run Coldstar on a dedicated machine that has never been connected to the internet. This eliminates the main weakness in Coldstar's threat model (OS compromise during signing) because there's no network for an attacker to reach through.

Coldstar enforces this with a kernel module whitelist — only USB storage, filesystem, and keyboard/mouse drivers are allowed to load. All network drivers (WiFi, Ethernet, Bluetooth) are blocked by default.

# Clone and download all dependencies offline
git clone https://github.com/devsyrem/coldstar /media/usb/coldstar
cd /media/usb/coldstar
pip download -r local_requirements.txt -d ./packages/

cd /media/usb/coldstar
python3 -m venv .venv
source .venv/bin/activate
pip install --no-index --find-links=./packages/ -r local_requirements.txt

USB ISO Builder

Don't have a spare computer for air-gapped signing? Coldstar can build a bootable USB that turns any machine into a dedicated signing device. Plug it in, boot from USB, and you have an air-gapped Coldstar environment — no hard drive, no network, no other software.

• Alpine Linux minirootfs — tiny operating system with minimal attack surface (no desktop, no browser, no extras)
• Kernel module whitelist — only allows USB storage, filesystem, and keyboard/mouse drivers to load
• All network drivers blocked — WiFi, Ethernet, and Bluetooth are denied at the kernel level, not just disabled
• Boots directly into Coldstar — no login screen, no shell, just the wallet TUI

View on GitHub · Documentation · Back to Home