Paladin Onboarding Wizard

Interactive setup wizard to configure your Paladin environment quickly and correctly.

Overview

The paladin onboarding command provides a step-by-step wizard that:

  • Guides you through provider selection (OpenAI, Anthropic, DeepSeek)
  • Securely collects and validates API keys
  • Creates/updates your .env file with proper configuration
  • Generates sample configuration files for quick start
  • Provides next steps and helpful resources

Quick Start

# Run the wizard
paladin onboarding

# Follow the interactive prompts
# ✓ Provider selection
# ✓ API key input (masked)
# ✓ Real-time validation
# ✓ Configuration file creation
# ✓ Sample generation

Wizard Flow

Step 1: Welcome Screen

╔══════════════════════════════════════════════════════════╗
║                                                          ║
║   Welcome to Paladin! 🛡️                                 ║
║                                                          ║
║   This wizard will help you set up your environment.    ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝

What Paladin can do:
  • Run autonomous AI agents (Paladins)
  • Orchestrate multi-agent battalions
  • Execute complex workflows with memory
  • Integrate external tools via Arsenal

Step 2: Provider Selection

Choose your LLM provider(s):

? Select your primary LLM provider:
  ❯ OpenAI (GPT-4, GPT-3.5)
    Anthropic (Claude 3)
    DeepSeek (DeepSeek V2)

Supported Providers:

ProviderModelsBest ForAPI Key Format
OpenAIGPT-4, GPT-3.5-turboGeneral purpose, function callingsk-...
AnthropicClaude 3 Opus/Sonnet/HaikuLong context, analysissk-ant-...
DeepSeekDeepSeek V2Cost-effective, code generationsk-...

Step 3: API Key Input

Secure API key collection with masking:

? Enter your OpenAI API key:
  [****************************************]

✓ Validating API key...
✓ Connection successful!
  Available models: gpt-4, gpt-3.5-turbo

Security Features:

  • ✅ Input is masked (not visible in terminal history)
  • ✅ Keys are validated before saving
  • ✅ Real API calls test connectivity
  • ✅ Clear error messages if validation fails

Step 4: API Key Validation

Real-time validation ensures your keys work:

Validating OpenAI API key...
  ✓ Authentication successful
  ✓ Models accessible: gpt-4, gpt-3.5-turbo
  ✓ Response time: 342ms

Configuration Status:
  ✓ OPENAI_API_KEY: Valid
  ⚠ ANTHROPIC_API_KEY: Not configured (optional)
  ⚠ DEEPSEEK_API_KEY: Not configured (optional)

Validation Process:

  1. Calls provider's authentication endpoint
  2. Lists available models
  3. Measures response time
  4. Reports any errors with suggestions

Step 5: Environment File Creation

The wizard creates or updates your .env file:

? .env file already exists. How should we proceed?
  ❯ Merge (combine with existing, no duplicates)
    Overwrite (replace completely)
    Skip (keep existing file)

Merge Strategy:

  • Preserves existing non-key configurations
  • Updates/adds API keys
  • Removes duplicate entries
  • Maintains comments and formatting where possible

Generated .env example:

# Paladin Environment Configuration
# Generated by onboarding wizard - 2026-02-09

# LLM Provider API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=sk-...

# Optional: Redis (for queue-based execution)
# REDIS_URL=redis://localhost:6379

# Optional: Qdrant (for vector storage/RAG)
# QDRANT_URL=http://localhost:6333

# Optional: MinIO (for file storage)
# MINIO_ENDPOINT=localhost:9000
# MINIO_ACCESS_KEY=minioadmin
# MINIO_SECRET_KEY=minioadmin

Step 6: Sample Configuration Generation

The wizard generates ready-to-use example files:

Generating sample configurations...
  ✓ examples/basic_paladin.yaml
  ✓ examples/formation.yaml
  ✓ examples/phalanx.yaml
  ✓ examples/paladin_with_rag.yaml

These examples demonstrate:
  • Basic single-agent configuration
  • Sequential execution (Formation)
  • Parallel execution (Phalanx)
  • RAG-enabled agent with memory

Step 7: Completion Summary

╔══════════════════════════════════════════════════════════╗
║                                                          ║
║   Setup Complete! ✅                                      ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝

Configuration saved to: .env
Sample configs created: examples/

Next Steps:
  1. Verify your setup:
     $ paladin setup-check

  2. Try a sample agent:
     $ paladin agent run -c examples/basic_paladin.yaml -i "Hello!"

  3. Explore features:
     $ paladin features

  4. Generate a battalion:
     $ paladin muster --task "Your task description"

Resources:
  • Documentation: docs/CLI_USAGE.md
  • Quick Start: docs/QUICKSTART.md
  • Architecture: docs/Design/Design_and_Architecture.md

Resumable Wizard State

The wizard automatically saves progress if interrupted:

# If interrupted (Ctrl+C)
^C
Saving wizard state...
Progress saved to: .paladin/onboarding.state

# Resume later
paladin onboarding
? Previous onboarding session found. Resume? (Y/n)

State Information:

  • Provider selections
  • Validated API keys
  • File merge decisions
  • Wizard step position

State Location: .paladin/onboarding.state (JSON format)

Troubleshooting

API Key Validation Fails

Problem: "Authentication failed" error

Solutions:

  1. Check key format:

    • OpenAI: Must start with sk- (51+ characters)
    • Anthropic: Must start with sk-ant- (40+ characters)
    • DeepSeek: Must start with sk- (40+ characters)

  2. Verify key is active:

    • Log into provider dashboard
    • Check API key hasn't been revoked
    • Verify account has credits/billing set up

  3. Network connectivity:

    # Test OpenAI connectivity
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

.env File Not Created

Problem: No .env file after completion

Solutions:

  1. Check file permissions:

    # Ensure write permissions in current directory
ls -la .

  2. Run with explicit output:

    # Check for error messages
paladin onboarding 2>&1 | tee onboarding.log

  3. Create manually:

    # Copy from template
cp examples/.env.template .env
# Edit with your keys
vim .env

Sample Configs Not Generated

Problem: Examples directory is empty

Solutions:

  1. Check directory exists:

    mkdir -p examples

  2. Verify write permissions:

    chmod 755 examples

  3. Generate manually:

    # Use agent command to create templates
paladin agent new -n basic -o examples/basic_paladin.yaml
paladin battalion new -n formation -t formation -o examples/formation.yaml

Advanced Usage

Non-Interactive Mode

For automation/scripting:

# Set via environment variables
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Run wizard with pre-set keys
paladin onboarding
# Will skip key input, validate, and proceed

Custom Output Path

# Generate .env in custom location
PALADIN_ENV_FILE=./config/.env paladin onboarding

Skip Validation

# For offline development (not recommended)
PALADIN_SKIP_VALIDATION=1 paladin onboarding

See Also