Installation

MothrBox is a self-hosted CLI tool that runs locally on your machine. Get up and running in just a few minutes with a simple bash setup.

Prerequisites

Before installing MothrBox, ensure you have:

  • Rust (v1.70 or higher)
  • Deno (v1.40 or higher)
  • Git (for cloning the repository)
  • Sui Wallet with testnet or mainnet tokens

Install Rust

Linux & macOS
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  source $HOME/.cargo/env
  
  # Verify installation
  rustc --version
  cargo --version
Windows
  # Download and run rustup-init.exe from:
  # https://rustup.rs/
  
  # Or use winget:
  winget install Rustlang.Rustup

Install Deno

Linux & macOS
  curl -fsSL https://deno.land/install.sh | sh
  
  # Add to PATH (add to ~/.bashrc or ~/.zshrc)
  export DENO_INSTALL="$HOME/.deno"
  export PATH="$DENO_INSTALL/bin:$PATH"
  
  # Verify installation
  deno --version
Windows
  # Using PowerShell
  irm https://deno.land/install.ps1 | iex
  
  # Or using winget:
  winget install DenoLand.Deno

Get a Sui Wallet

You'll need a Sui wallet with tokens for storing data on Walrus Protocol:

For Testnet (Recommended for development):

  1. Install Sui CLI: cargo install --locked --git https://github.com/MystenLabs/sui.git sui
  2. Create wallet: sui client new-address ed25519
  3. Get testnet tokens: https://faucet.testnet.sui.io/

For Mainnet:

  • Use Sui Wallet browser extension
  • Purchase SUI tokens from exchanges

Installation Steps

Step 1: Clone the Repository

git clone https://github.com/georgegoldman/mothrbox_v2
cd mothrbox_v2

Step 2: Make CLI Executable

chmod +x mothrbox

Step 3: Configure Your Sui Wallet

# Navigate to TypeScript client directory
cd mothrbox_ts

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env

Add your Sui wallet credentials to .env:

# Required - Your Sui wallet private key
SUI_SECRET_KEY=suiprivkey1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Network (testnet or mainnet)
SUI_NETWORK=testnet

# Optional - Walrus endpoints (defaults provided)
WALRUS_PUBLISHER=https://publisher.walrus-testnet.walrus.space
WALRUS_AGGREGATOR=https://aggregator.walrus-testnet.walrus.space

⚠️ Security: Never commit your .env file or share your SUI_SECRET_KEY. Treat it like a password.

Step 4: Build MothrBox

# Return to project root
cd ..

# Build the project
./mothrbox build

This process may take a few minutes as it:

  • Builds the Rust encryption engine
  • Sets up the Deno Walrus client
  • Compiles all dependencies

Step 5: Verify Installation

# Check status
./mothrbox status

If everything is working, you should see:

✅ Rust engine: Built
✅ TypeScript client: Ready
✅ Configuration: Valid

Quick Test

Let's verify all three encryption methods work:

# Create a test file
echo "MothrBox test data" > test.txt

# Test AES-256-GCM
./mothrbox encrypt test.txt "TestPass123"
# Save the blob ID, then:
./mothrbox decrypt <blob-id> aes_recovered.txt "TestPass123"

# Test ChaCha20-Poly1305
./mothrbox chacha-encrypt test.txt "TestPass123"
./mothrbox chacha-decrypt <blob-id> chacha_recovered.txt "TestPass123"

# Test ECC
./mothrbox keygen
./mothrbox ecc-encrypt test.txt data/public.key
./mothrbox ecc-decrypt <blob-id> ecc_recovered.txt data/private.key

# Verify all worked
diff test.txt data/aes_recovered.txt && echo "✅ AES works"
diff test.txt data/chacha_recovered.txt && echo "✅ ChaCha20 works"
diff test.txt data/ecc_recovered.txt && echo "✅ ECC works"

Directory Structure

After installation, your project structure looks like this:

mothrbox_v2/
├── mothrbox              # Main CLI script
├── data/                 # Your encrypted/decrypted files
├── mothrbox_rs/          # Rust encryption engine
│   └── target/          # Compiled Rust binaries
├── mothrbox_ts/          # Deno Walrus client
│   └── .env             # Your configuration (keep secret!)
└── README.md

Updating MothrBox

To update to the latest version:

# Pull latest changes
git pull origin main

# Rebuild components
./mothrbox build

# Verify update
./mothrbox --version

Troubleshooting

Issue: Rust Not Found

# Verify Rust is installed
rustc --version
cargo --version

# If not installed, see Prerequisites section above

# Ensure Rust is in PATH
source $HOME/.cargo/env

Issue: Deno Not Found

# Verify Deno is installed
deno --version

# If not installed, see Prerequisites section above

# Ensure Deno is in PATH
export PATH="$HOME/.deno/bin:$PATH"

Issue: Permission Denied

# Make script executable
chmod +x mothrbox

# Fix data directory permissions
chmod -R 755 data/

Issue: Build Fails

# Clean and rebuild
./mothrbox clean
./mothrbox build

# Check Rust toolchain
rustup update

# Check disk space
df -h

# Verify all dependencies
rustc --version
cargo --version
deno --version

Issue: Missing SUI_SECRET_KEY

# Check your .env file
cat mothrbox_ts/.env

# Should contain:
# SUI_SECRET_KEY=suiprivkey1...
# SUI_NETWORK=testnet

# If missing, reconfigure:
cd mothrbox_ts
cp .env.example .env
nano .env

Issue: Upload Fails (Insufficient SUI)

# For testnet, get free tokens:
# Visit: https://faucet.testnet.sui.io/
# Enter your wallet address

# Check your balance
sui client balance

# For mainnet, purchase SUI tokens from exchanges

Issue: Compilation Errors

# Update Rust toolchain
rustup update stable
rustup default stable

# Clear Cargo cache
cargo clean

# Rebuild from scratch
cd mothrbox_rs
cargo build --release
cd ..

Uninstallation

To completely remove MothrBox:

# Remove all build artifacts
./mothrbox clean

# Remove repository
cd ..
rm -rf mothrbox_v2

# (Optional) Remove Rust and Deno if not needed for other projects
# rustup self uninstall
# rm -rf ~/.deno

System Requirements

Minimum Requirements

  • OS: Linux, macOS, Windows (with WSL2 or native)
  • CPU: 2 cores
  • RAM: 2GB
  • Disk: 2GB free space
  • Network: Stable internet connection
  • CPU: 4+ cores
  • RAM: 4GB+
  • Disk: 5GB+ free space
  • Network: High-speed connection for large file uploads

Network Configuration

MothrBox connects to:

  • Walrus Protocol (testnet/mainnet) - Decentralized storage
  • Sui Blockchain (testnet/mainnet) - Storage proofs and metadata

Ensure your firewall allows outbound connections to:

  • publisher.walrus-testnet.walrus.space (or mainnet equivalent)
  • aggregator.walrus-testnet.walrus.space (or mainnet equivalent)
  • fullnode.testnet.sui.io (or mainnet equivalent)

Next Steps

Now that MothrBox is installed:

  1. 📖 Read the CLI Reference - Learn all available commands
  2. 🔐 Review Security Best Practices - Protect your data properly
  3. 🚀 Try Advanced Usage - Batch operations, automation
  4. 🏗️ Understand the Architecture - How it all works

Getting Help

If you encounter issues not covered here:

  • 🐙 GitHub Issues: Report a bug
  • 📖 Documentation: Check other docs pages
  • 💬 Community: Join our Discord (coming soon)

Environment Variables Reference

Complete .env configuration options:

# Required
SUI_SECRET_KEY=suiprivkey1...           # Your Sui wallet private key
SUI_NETWORK=testnet                     # Network: testnet or mainnet

# Optional - Walrus Endpoints
WALRUS_PUBLISHER=https://publisher.walrus-testnet.walrus.space
WALRUS_AGGREGATOR=https://aggregator.walrus-testnet.walrus.space

# Optional - Storage Configuration
WALRUS_EPOCHS=3                         # Storage duration (epochs)

# Optional - Advanced
LOG_LEVEL=info                          # Log verbosity: debug, info, warn, error

💡 Pro Tip: After installation, bookmark the Quick Reference for fast command lookups.

You're all set! MothrBox is now ready to encrypt and store your data securely. 🦋🔒