Installation

Installation Guide

Install UniCraft

Choose your preferred installation method and get UniCraft AI Model Router running in your environment

Installation Methods

🐳 Docker (Recommended)

Docker is the easiest and most reliable way to run UniCraft. It includes all dependencies and ensures consistent behavior across different environments.

# Pull the latest image docker pull ghcr.io/cloudcrafttech/unicraft:latest

Run UniCraft with basic configuration

docker run -d
—name unicraft
-p 8080:8080
-e OPENAI_API_KEY=your_openai_key
-e ANTHROPIC_API_KEY=your_anthropic_key
-e GOOGLE_API_KEY=your_google_key
ghcr.io/cloudcrafttech/unicraft:latest

Docker Compose

For more complex deployments, use Docker Compose:

version: '3.8'

services: unicraft: image: ghcr.io/cloudcrafttech/unicraft:latest container_name: unicraft ports: - “8080:8080” environment: # Core Configuration - UNICRAFT_PORT=8080 - UNICRAFT_HOST=0.0.0.0 - UNICRAFT_LOG_LEVEL=info

  # Provider API Keys
  - OPENAI_API_KEY=${OPENAI_API_KEY}
  - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  - GOOGLE_API_KEY=${GOOGLE_API_KEY}
  - AZURE_OPENAI_API_KEY=${AZURE_OPENAI_API_KEY}
  - AZURE_OPENAI_ENDPOINT=${AZURE_OPENAI_ENDPOINT}
  - COHERE_API_KEY=${COHERE_API_KEY}
  - HUGGINGFACE_API_KEY=${HUGGINGFACE_API_KEY}

  # Smart Routing Configuration
  - SMART_ROUTING_ENABLED=true
  - SMART_ROUTING_STRATEGY=cost-performance
  - COST_OPTIMIZATION_ENABLED=true

volumes:
  - unicraft_data:/app/data
  - unicraft_logs:/app/logs

restart: unless-stopped

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

volumes: unicraft_data: unicraft_logs:

# Create .env file with your API keys cp .env.example .env # Edit .env with your API keys

Start the services

docker-compose up -d

Check logs

docker-compose logs -f unicraft

📦 npm Package

Install UniCraft as a Node.js package for development or custom deployments:

# Install UniCraft npm install @cloudcraftlabs/unicraft

Or install globally

npm install -g @cloudcraftlabs/unicraft

const { UniCraft } = require('@cloudcraftlabs/unicraft');

// Initialize UniCraft const unicraft = new UniCraft({ port: 8080, providers: { openai: { apiKey: process.env.OPENAI_API_KEY }, anthropic: { apiKey: process.env.ANTHROPIC_API_KEY } } });

// Start the server unicraft.start().then(() => { console.log(‘UniCraft is running on http://localhost:8080’); });

🔧 Source Code

For development or custom builds, install from source:

# Clone the repository git clone https://github.com/cloudcrafttech/unicraft.git cd unicraft

Install dependencies

npm install

Build the project

npm run build

Start in development mode

npm run dev

Or start in production mode

npm start

Development Setup

# Install development dependencies npm install

Set up environment variables

cp .env.example .env

Edit .env with your configuration

Run in development mode with hot reload

npm run dev

Run tests

npm test

Run linting

npm run lint

Build for production

npm run build

☁️ Cloud Deployments

Railway

Deploy to Railway with one click:

Render

Deploy to Render:

services: - type: web name: unicraft env: docker dockerfilePath: ./Dockerfile envVars: - key: OPENAI_API_KEY sync: false - key: ANTHROPIC_API_KEY sync: false - key: GOOGLE_API_KEY sync: false healthCheckPath: /health

Vercel

Deploy to Vercel using the Vercel CLI:

# Install Vercel CLI npm i -g vercel

Deploy

vercel —prod

Set environment variables

vercel env add OPENAI_API_KEY vercel env add ANTHROPIC_API_KEY vercel env add GOOGLE_API_KEY

System Requirements

Minimum Requirements

• CPU: 1 vCPU
• Memory: 512 MB RAM
• Storage: 1 GB available space
• Network: Internet connection for API calls

Recommended Requirements

• CPU: 2+ vCPUs
• Memory: 2+ GB RAM
• Storage: 5+ GB available space
• Network: Stable internet connection

Supported Platforms

• ✅ Linux (Ubuntu 20.04+, CentOS 8+, Debian 11+)
• ✅ macOS (10.15+)
• ✅ Windows (10+, with WSL2 recommended)
• ✅ Docker (Any platform with Docker support)
• ✅ Kubernetes (1.20+)

Environment Configuration

Required Environment Variables

# At least one AI provider API key is required OPENAI_API_KEY=your_openai_api_key_here # OR ANTHROPIC_API_KEY=your_anthropic_api_key_here # OR GOOGLE_API_KEY=your_google_api_key_here

Optional Environment Variables

# Server Configuration UNICRAFT_PORT=8080 UNICRAFT_HOST=0.0.0.0 UNICRAFT_LOG_LEVEL=info

Database Configuration (optional)

DATABASE_URL=sqlite://./data/unicraft.db

OR for PostgreSQL

DATABASE_URL=postgresql://user:password@localhost:5432/unicraft

Redis Configuration (optional, for caching)

REDIS_URL=redis://localhost:6379

Authentication (optional)

JWT_SECRET=your_jwt_secret_here API_KEY=your_api_key_here

Smart Routing Configuration

SMART_ROUTING_ENABLED=true SMART_ROUTING_STRATEGY=cost-performance COST_OPTIMIZATION_ENABLED=true CIRCUIT_BREAKER_ENABLED=true

Monitoring and Analytics

ANALYTICS_ENABLED=true METRICS_ENABLED=true

Verification

After installation, verify that UniCraft is running correctly:

<InteractiveDemo title=“Installation Verification” description=“Follow these steps to verify your UniCraft installation” steps={[ { title: “Check Health Endpoint”, content: “Visit http://localhost:8080/health to verify the service is running”, code: “curl http://localhost:8080/health” }, { title: “Test API Endpoint”, content: “Make a simple API call to test functionality”, code: curl -X POST http://localhost:8080/v1/chat/completions \\ -H "Content-Type: application/json" \\ -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 10}' }, { title: “Check Web Interface”, content: “Open http://localhost:8080 in your browser to access the web interface”, code: “open http://localhost:8080” }, { title: “Verify Provider Configuration”, content: “Check that your AI providers are properly configured in the web interface”, code: “Check the Providers section in the web interface” } ]} />

Troubleshooting

Common Installation Issues

Docker Issues

Issue: docker: command not found Solution: Install Docker Desktop or Docker Engine

Issue: Port 8080 is already in use Solution: Change the port using -p 8081:8080 or stop the service using port 8080

Issue: Container keeps restarting Solution: Check logs with docker logs unicraft and verify environment variables

Node.js Issues

Issue: npm: command not found Solution: Install Node.js 18+ from nodejs.org

Issue: Permission denied errors Solution: Use sudo for global installs or configure npm to use a different directory

Issue: Module not found errors Solution: Run npm install in the project directory

API Key Issues

Issue: Invalid API key errors Solution:

• Verify your API key is correct
• Check that the API key has sufficient credits
• Ensure the environment variable is set correctly

Issue: Provider not available Solution:

• Check your internet connection
• Verify the provider’s API is accessible
• Check for any firewall restrictions

Getting Help

If you’re still having issues:

1. Check the logs: docker logs unicraft or npm run dev
2. Verify configuration: Ensure all required environment variables are set
3. Test connectivity: Make sure you can reach the AI provider APIs
4. Check documentation: Review the API Reference and Configuration guides
5. Get support: Join our Discord community or create an issue

---

🎉 Installation Complete! UniCraft is now installed and ready to use. Check out the [Quick Start Guide](/quick-start/) to make your first API call.

💡 Next Steps: After installation, configure your [AI providers](/guides/setting-up-providers/) and explore the [Smart Routing](/features/smart-routing/) features.