Getting Started with VEX#

Get up and running with VEX in under 5 minutes.

Prerequisites#

Rust 1.75+ (stable toolchain)
Git

Installation#

Add to Your Project#

TOML

# Cargo.toml
[dependencies]
vex-core = { git = "https://github.com/provnai/vex" }
vex-adversarial = { git = "https://github.com/provnai/vex" }
vex-llm = { git = "https://github.com/provnai/vex" }

Clone and Build#

Bash

git clone https://github.com/provnai/vex.git
cd vex
cargo build --workspace --release

Project Structure#

Understanding the workspace layout is crucial for effective development:

Code

vex/
├── crates/
│   ├── vex-core/        # Core types (Agent, Genome, Merkle)
│   ├── vex-adversarial/ # Debate engine & consensus
│   ├── vex-temporal/    # Memory horizons & decay
│   ├── vex-llm/         # LLM provider traits & MCP
│   ├── vex-router/      # Intelligent routing & caching
│   ├── vex-algoswitch/  # Runtime optimization
│   ├── vex-api/         # Axum web server & A2A
│   ├── vex-persist/     # SQLite, VectorStore, Evolution
│   ├── vex-anchor/      # Multi-chain anchoring
│   ├── vex-queue/       # Background job processing
│   ├── vex-runtime/     # Agent orchestration
│   ├── vex-macros/      # Procedural macros
│   └── vex-cli/         # CLI verify/tools
├── examples/            # Standalone examples
├── Cargo.toml           # Workspace configuration
└── .env.example         # Template for environment variables

Quick Example#

Rust

use vex_core::{Agent, AgentConfig};
use vex_llm::MockProvider;

#[tokio::main]
async fn main() {
    // Create an agent
    let agent = Agent::new(AgentConfig {
        name: "Researcher".to_string(),
        role: "You are a helpful research assistant".to_string(),
        max_depth: 3,
        spawn_shadow: true,
    });

    // Use with an LLM provider
    let llm = MockProvider::smart();
    let response = llm.ask("What is quantum computing?").await.unwrap();
    
    println!("Response: {}", response);
}

Running the Demo#

Bash

# Set up API key (optional, uses mock if not set)
export DEEPSEEK_API_KEY="sk-..."

# Run the research agent demo
cargo run -p vex-demo

# Run fraud detection demo
cargo run -p vex-demo --bin fraud-detector

# Interactive chat
cargo run -p vex-demo --bin interactive

Running the API Server#

Bash

export VEX_JWT_SECRET="your-32-char-secret-here"
cargo run -p vex-api
# Server starts on 0.0.0.0:3000

Configuration & Environment#

VEX uses dotenv to load configuration. Create a .env file in your project root:

Bash

# LLM Providers (At least one is required)
DEEPSEEK_API_KEY="sk-..."       # For DeepSeek (Default recommended)
OPENAI_API_KEY="sk-..."         # For OpenAI
MISTRAL_API_KEY="sk-..."        # For Mistral
ANTHROPIC_API_KEY="sk-..."      # For Anthropic/Claude
OLLAMA_URL="http://localhost:11434" # For local LLMs

# Agent Configuration (Optional defaults)
VEX_DEFAULT_PROVIDER="deepseek"  # deepseek, openai, mistral, anthropic, ollama
VEX_DEFAULT_MODEL="deepseek-chat"
VEX_MAX_DEPTH="5"                # Max recursion depth for fractal agents
VEX_ADVERSARIAL="true"           # Enable/disable ShadowAgent verification
VEX_DEBUG="false"                # Enable verbose agent thought process logs

# Security & API
VEX_JWT_SECRET="your-super-secret-32-char-key-must-be-long"
VEX_ENV="development"            # development | production

# Database & Persistence
DATABASE_URL="sqlite://vex.db"   # Main storage
REDIS_URL="redis://localhost:6379" # Optional: For distributed job queue

# Rate Limiting & Routing (vex-api / vex-router)
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60             # Window size in seconds
ROUTING_STRATEGY="cost"          # cost | quality | balanced

# Blockchain Anchoring (vex-anchor)
ETH_RPC_URL="https://..."        # Ethereum RPC for anchoring
CELESTIA_RPC_URL="https://..."   # Celestia RPC for blobs
OTS_API_URL="https://..."        # OpenTimestamps API

# Compliance (ISO 42001)
VEX_COMPLIANCE_MODE="true"       # Enable pseudonymization & sigs
VEX_TENANT_ID="tenant-123"

# Telemetry & Observability
RUST_LOG="info,vex_core=debug"   # Log levels
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317" # Jaeger/Prometheus endpoint

Step-by-Step Setup#

Install Rust:

Bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone Repository:

Bash

git clone https://github.com/provnai/vex.git
cd vex

Install Dependencies: (VEX requires sqlx-cli for database migrations)
Bash
```
cargo install sqlx-cli
```

Initialize Database:

Bash

# Create .env file first
echo 'DATABASE_URL="sqlite://vex.db"' > .env
sqlx database create
sqlx migrate run --source crates/vex-persist/migrations

Run Tests: Ensure everything is working correctly.
Bash
```
cargo test --workspace
```

Next Steps#

API Reference — Full Rustdoc documentation
Examples — More code examples
Architecture — System design