Self-Hosted Installation

Deploy Kortix on your own infrastructure with the automated setup wizard

Overview

Kortix can be self-hosted using either Docker Compose (recommended) or manual installation. The automated setup wizard (setup.py) handles all configuration, from dependencies to database initialization.

System Requirements

Hardware

• CPU: 4+ cores recommended
• RAM: 8GB minimum, 16GB recommended
• Storage: 20GB+ free space

Software

• OS: Linux, macOS, or Windows (WSL2)
• Python: 3.11 or higher
• Node.js: 18.x or higher
• Docker: Latest version (for Docker setup)

Installation Methods

Choose between two setup methods:

Docker (Recommended)

Docker Setup

The Docker setup runs all services in containers for isolation and easy management.

Advantages:

• Isolated environments
• Easy deployment and scaling
• Consistent across platforms
• Simple service management

Services:

• Redis (containerized)
• Backend API (containerized)
• Frontend (containerized)
• Agent runtime (containerized)

Currently, local Supabase is not supported with Docker Compose. Use cloud Supabase for Docker setups.

Manual

Manual Setup

The manual setup runs services natively on your system.

Advantages:

• Full control over services
• Supports local Supabase
• Easier debugging
• Lower resource overhead

Services:

• Redis (Docker container)
• Backend API (native process)
• Frontend (native process)

Additional Requirements:

• pnpm package manager
• uv Python package installer

Step-by-Step Installation

1. Clone the Repository

   git clone https://github.com/kortix-ai/suna.git
   cd suna
   
2. Run the Setup Wizard

   Launch the interactive setup wizard:

   python setup.py
   

   The wizard automatically:

   • Checks system dependencies
   • Installs required Python packages (pydantic, rich)
   • Guides you through configuration
   • Saves progress for resumable setup

   If interrupted, simply run python setup.py again to resume from where you left off.

3. Choose Setup Method

   The wizard will ask you to choose:

   How would you like to set up Kortix?
     [1] Docker - Run all services in containers (recommended)
     [2] Manual - Run services natively on your system
   

   Select based on your preference and requirements.

4. Verify Dependencies

   The wizard checks for required tools:

   For Docker Setup:

   • Docker and Docker Compose
   • Git

   For Manual Setup:

   • Python 3.11+
   • Node.js 18+
   • pnpm
   • uv (Python package installer)
   • Git
   • Docker (for Redis only)

   Missing dependencies will be flagged. Install them before continuing.

5. Configure Supabase

   Choose your Supabase setup:

   How would you like to set up Supabase?
     [1] Use Kortix Cloud Supabase (easiest)
     [2] Use your own cloud Supabase
     [3] Use local Supabase (manual setup only)
   

   Kortix Cloud Supabase

   # Uses pre-configured staging Supabase
   # No additional setup required
   # Recommended for quick start
   
6. Configure LLM Providers

   Add API keys for your preferred LLM providers:

   Anthropic (Claude)

   Enter your Anthropic API key: sk-ant-...
   

   Get your key from: https://console.anthropic.com/

   OpenAI

   Enter your OpenAI API key: sk-...
   

   Get your key from: https://platform.openai.com/api-keys

   Groq

   Enter your Groq API key: gsk_...
   

   Get your key from: https://console.groq.com/keys

   Together AI

   Enter your Together AI API key: ...
   

   Get your key from: https://api.together.xyz/settings/api-keys

   You can configure multiple providers and switch between them in the dashboard.

7. Configure Optional Integrations

   The wizard will prompt for optional services:

   Search APIs

   Tavily Search API

   • Enables web search capabilities
   • Get key from: https://tavily.com/

   Firecrawl API

   • Web scraping and crawling
   • Get key from: https://firecrawl.dev/

   RapidAPI

   • Access to various third-party APIs
   • Get key from: https://rapidapi.com/

   Composio

   • Pre-built integrations for 200+ apps
   • Get key from: https://app.composio.dev/

   MCP Tools

   • Model Context Protocol integration
   • Extend agents with custom tools
   • Configure during setup or later

   All integrations are optional. Skip any you don’t need and add them later.

8. Environment Generation

   The wizard automatically generates configuration files:

   ✓ Writing backend/.env
   ✓ Writing apps/frontend/.env
   ✓ Validating configuration
   

   Files created:

   • backend/.env - Backend API configuration
   • apps/frontend/.env - Frontend configuration
   • .setup_progress - Resume state (can be deleted after setup)
9. Database Initialization

   The wizard sets up the database schema:

   ✓ Connecting to Supabase
   ✓ Creating tables
   ✓ Running migrations
   ✓ Setting up authentication
   

   This creates all necessary tables for:

   • User authentication
   • Agent configurations
   • Conversation threads
   • File storage
   • Workflow state
10. Install Dependencies

    The wizard installs required packages:

    Docker Setup

    ✓ Building Docker images
    ✓ Pulling base images
    ✓ Installing dependencies in containers
    

Starting Kortix

After installation, use the service manager:

Interactive Mode

python start.py

Service Manager Features

The start.py script automatically:

• Detects your setup method (Docker or Manual)
• Manages appropriate services
• Shows real-time status
• Handles graceful shutdown
• Provides log file locations

Manual Setup Services

# Redis (Docker container)
docker compose up -d redis

# Backend (native process)
cd backend && uv run api.py

# Frontend (native process) 
cd apps/frontend && pnpm run dev

Monitoring and Logs

Manual Setup

# View both backend and frontend logs
tail -f backend.log frontend.log

# View backend only
tail -f backend.log

# View frontend only
tail -f frontend.log

Log files are created in the repository root.

Docker Setup

# View all service logs
docker compose logs -f

# View specific service
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f redis

# Last 100 lines
docker compose logs --tail=100

Updating Configuration

To add or update API keys after installation:

python setup.py

The wizard offers options to:

1. Add/Update API Keys - Modify existing configuration
2. Clear setup and start fresh - Remove all configuration

Clearing setup will delete all .env files and progress state.

Architecture Deep Dive

Kortix consists of four main components:

1. Backend API (Port 8000)

Python/FastAPI service providing:

# Core API modules
- /v1/agents      # Agent management
- /v1/threads     # Conversation threads
- /v1/runs        # Agent executions
- /v1/tools       # Tool registry
- /v1/mcp         # MCP integration
- /v1/knowledge   # Knowledge bases

Key Features:

• REST API endpoints
• Thread management
• Agent orchestration
• LLM integration via LiteLLM
• Tool execution
• WebSocket streaming

2. Frontend Dashboard (Port 3000)

Next.js/React application:

// Main features
- Chat interface
- Agent builder
- Workflow designer
- Monitoring dashboard
- Settings management

Technologies:

• Next.js 14+
• React 18+
• Tailwind CSS
• Supabase Auth

3. Agent Runtime

Isolated Docker containers for each agent:

services:
  agent-runtime:
    image: kortix-agent-runtime
    features:
      - Browser automation (Playwright)
      - Code interpreter (Python)
      - File system access
      - Tool integration
      - Security sandboxing

4. Database & Storage

Supabase provides:

-- Core tables
users                 -- User accounts
agents                -- Agent configurations  
threads               -- Conversation threads
messages              -- Chat messages
runs                  -- Execution records
tools                 -- Available tools
knowledge_bases       -- Agent knowledge

Network Configuration

Default Ports

Service	Port	Description
Frontend	3000	Web dashboard
Backend	8000	REST API
Redis	6379	Message queue
Supabase	54321	Local DB (manual only)

DNS Configuration

Docker setup uses optimized DNS:

# docker-compose.yaml
dns:
  - 8.8.8.8      # Google DNS
  - 1.1.1.1      # Cloudflare DNS
dns_search:
  - .

This reduces DNS lookup latency for third-party API calls.

Security Best Practices

Critical Security Steps:

1. Never commit .env files to version control
2. Use strong database passwords
3. Rotate API keys regularly
4. Enable HTTPS in production
5. Restrict network access to necessary ports
6. Keep Docker images updated

Production Checklist

1. Environment Variables

   • Store secrets in a secure vault (e.g., AWS Secrets Manager)
   • Use separate credentials for production
   • Enable environment variable validation
2. Database Security

   • Enable Row Level Security (RLS) in Supabase
   • Use connection pooling
   • Configure backup retention
   • Enable audit logging
3. Network Security

   • Deploy behind a reverse proxy (nginx, Caddy)
   • Enable HTTPS with valid certificates
   • Configure CORS policies
   • Use VPC for internal services
4. Monitoring

   • Set up health checks
   • Configure alerting
   • Enable application logging
   • Monitor resource usage

Troubleshooting

Setup wizard fails to install dependencies

Problem: Missing pydantic or rich packages

Solution:

# Manual installation
pip install pydantic rich

# Or with uv
uv pip install pydantic rich

# Then re-run setup
python setup.py

Docker Compose command not found

Problem: Docker Compose not installed

Solution:

# For Docker Desktop (Mac/Windows)
# Install from docker.com

# For Linux
sudo apt-get install docker-compose-plugin

# Verify installation
docker compose version

Port conflicts (3000 or 8000 already in use)

Problem: Another service is using required ports

Solution:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or modify ports in docker-compose.yaml
ports:
  - "3001:3000"  # Map to different host port

Database connection errors

Problem: Cannot connect to Supabase

Solution:

• Verify credentials in backend/.env
• Check network connectivity
• For local Supabase: npx supabase status
• For cloud: verify project is active
• Check firewall rules

Frontend build fails

Problem: pnpm build errors

Solution:

# Clear cache and reinstall
cd apps/frontend
rm -rf node_modules .next
pnpm install
pnpm run build

# If still failing, check Node version
node --version  # Should be 18+

Backend API errors

Problem: 500 errors from backend

Solution:

# Check backend logs
tail -f backend.log

# Or for Docker
docker compose logs backend

# Common issues:
# - Missing API keys in .env
# - Invalid Supabase credentials
# - Redis not running

Uninstalling

To completely remove Kortix:

Docker Setup

# Stop and remove all services
docker compose down -v

# Remove images
docker rmi $(docker images 'ghcr.io/suna-ai/*' -q)

# Delete repository
cd ..
rm -rf suna

Next Steps

Configuration Guide

Deep dive into environment variables and settings

Deploy to Production

Production deployment best practices

API Reference

Explore the complete REST API

Agent Development

Start building custom agents

For deployment to cloud platforms (AWS, GCP, Azure), see our Cloud Deployment Guide.