Installation Guide

This guide provides detailed installation instructions for Paladin on Linux, macOS, and Windows.

Prerequisites

Required

• Rust 1.70 or later: https://rustup.rs/
• Cargo: Included with Rust installation
• LLM API Key: OpenAI, DeepSeek, or Anthropic account

Optional

• Docker: For containerized deployment (see Docker Guide)
• Redis: For async queue functionality (see Development Setup)
• MinIO: For file storage (see Development Setup)

Platform-Specific Setup

Linux

Ubuntu/Debian

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install system dependencies
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev

# Verify installation
rustc --version
cargo --version

Fedora/RHEL/CentOS

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install system dependencies
sudo dnf install -y gcc pkg-config openssl-devel

# Verify installation
rustc --version
cargo --version

Arch Linux

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install system dependencies
sudo pacman -S base-devel openssl pkg-config

# Verify installation
rustc --version
cargo --version

macOS

Using Homebrew

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install OpenSSL (if needed)
brew install openssl pkg-config

# Verify installation
rustc --version
cargo --version

Apple Silicon (M1/M2/M3)

Rust supports Apple Silicon natively. No additional steps required:

# Verify architecture
rustc --version --verbose | grep host
# Should show: host: aarch64-apple-darwin

Windows

Using rustup-init.exe

1. Download rustup-init.exe from https://rustup.rs/
2. Run the installer and follow prompts
3. Restart your terminal

# Verify installation
rustc --version
cargo --version

Using WSL2 (Recommended for Development)

# Inside WSL2 Ubuntu
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install dependencies
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev

# Verify installation
rustc --version
cargo --version

Installing Paladin

Option 1: From Crates.io (Stable)

# Add Paladin to your project
cargo add paladin

# Or manually edit Cargo.toml

[dependencies]
paladin = "0.1"
tokio = { version = "1", features = ["full"] }

Option 2: From Source (Latest)

# Clone the repository
git clone https://github.com/DF3NDR/paladin-dev-env.git
cd paladin-dev-env

# Build the project
cargo build --release

# Run tests to verify
cargo test

# Optionally install CLI tools
cargo install --path .

Option 3: As a Dependency from Git

[dependencies]
paladin = { git = "https://github.com/DF3NDR/paladin-dev-env", branch = "main" }
tokio = { version = "1", features = ["full"] }

Feature Flags

Paladin supports optional features that can be enabled in Cargo.toml:

[dependencies.paladin]
version = "0.1"
features = [
    "redis-queue",      # Enable Redis queue adapter (default)
    "s3-storage",       # Enable MinIO/S3 storage (default)
    "anthropic",        # Enable Anthropic LLM provider
    "deepseek",         # Enable DeepSeek LLM provider
    "mcp",              # Enable MCP tool protocol
]

Default Features

Enabled by default:

• redis-queue - Redis-based async queue
• s3-storage - MinIO/S3 file storage

Optional Features

Not enabled by default:

• anthropic - Anthropic Claude integration
• deepseek - DeepSeek LLM integration
• mcp - Model Context Protocol for tools

Disable default features:

[dependencies.paladin]
version = "0.1"
default-features = false
features = ["mcp"]  # Only enable MCP

Environment Configuration

API Keys

Create a .env file in your project root:

# OpenAI (default provider)
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1  # Optional

# DeepSeek
DEEPSEEK_API_KEY=your-deepseek-key
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1  # Optional

# Anthropic
ANTHROPIC_API_KEY=your-anthropic-key
ANTHROPIC_BASE_URL=https://api.anthropic.com/v1  # Optional

Configuration File

Create config.yml (optional):

paladin:
  default_model: "gpt-4"
  default_temperature: 0.7
  default_max_loops: 3
  timeout_seconds: 300

garrison:
  type: "sqlite"  # or "in_memory"
  path: "./garrison.db"
  max_entries: 1000

llm:
  openai:
    api_key: "${OPENAI_API_KEY}"
    base_url: "https://api.openai.com/v1"

Development Setup

For local development with all features:

1. Clone the Repository

git clone https://github.com/DF3NDR/paladin-dev-env.git
cd paladin-dev-env

2. Install Development Dependencies

# Install additional cargo tools
cargo install cargo-watch      # Auto-rebuild on changes
cargo install cargo-edit        # cargo add/rm commands
cargo install cargo-audit       # Security vulnerability scanning
cargo install cargo-llvm-cov    # Code coverage
cargo install cargo-insta       # Snapshot testing (for CLI output tests)

cargo-insta is used for CLI snapshot testing. It allows you to capture and verify terminal output:

# Run snapshot tests
cargo test --test cli

# Review new snapshots
cargo insta review

# Accept all pending snapshots
cargo insta accept

See tests/cli/ for snapshot test examples.

3. Start Docker Services (Optional)

# Start Redis and MinIO
make dev

# Or manually with docker-compose
docker-compose -f docker/docker-compose.dev.yml up -d

4. Configure Environment

# Copy example environment
cp .env.example .env

# Edit with your API keys
vim .env

5. Build and Test

# Build the project
cargo build

# Run tests
cargo test

# Run with auto-reload
cargo watch -x run

Verification

Quick Test

Create test.rs:

use paladin::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Paladin version: {}", env!("CARGO_PKG_VERSION"));
    println!("Installation successful!");
    Ok(())
}

Run:

cargo run --example test

Full System Test

# Run all tests
cargo test

# Run integration tests (requires Docker services)
make test-integration-docker

# Run benchmarks
cargo bench

Troubleshooting

OpenSSL Errors (Linux)

# Ubuntu/Debian
sudo apt-get install pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install pkgconfig openssl-devel

# Arch
sudo pacman -S openssl pkg-config

Linking Errors (Windows)

Install Visual Studio Build Tools:

• Download from https://visualstudio.microsoft.com/downloads/
• Select "Desktop development with C++"

Permission Errors (macOS)

# Fix cargo permissions
sudo chown -R $(whoami) ~/.cargo

Slow Compilation

Enable parallel compilation:

# Add to ~/.cargo/config.toml
[build]
jobs = 8  # Adjust based on CPU cores

Use sccache for caching:

cargo install sccache
export RUSTC_WRAPPER=sccache

Network Issues

Use a proxy:

# Set in ~/.cargo/config.toml
[http]
proxy = "http://proxy.example.com:8080"

[https]
proxy = "http://proxy.example.com:8080"

Or use a mirror:

[source.crates-io]
replace-with = "ustc"

[source.ustc]
registry = "https://mirrors.ustc.edu.cn/crates.io-index"

Next Steps

• Quickstart Guide - Build your first Paladin agent
• Configuration Guide - Advanced configuration
• Examples - Working code examples
• API Reference - Complete API documentation

Platform Support

Minimum System Requirements

• CPU: 2 cores (4+ recommended for parallel operations)
• RAM: 4 GB (8+ GB recommended)
• Disk: 2 GB for dependencies and builds
• Network: Internet connection for LLM API calls

Get Help

• Installation Issues: GitHub Issues
• General Questions: GitHub Discussions
• Documentation: docs/