Self-Hosted Installation

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)
Manual

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 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

Clone the Repository

git clone https://github.com/kortix-ai/suna.git
cd suna

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.

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.

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.

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)

# Uses pre-configured staging Supabase
# No additional setup required
# Recommended for quick start

Configure LLM Providers

Add API keys for your preferred LLM providers:

Anthropic (Claude)
OpenAI
Groq
Together AI

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

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

Enter your OpenAI API key: sk-...

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

Enter your Groq API key: gsk_...

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

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.

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.

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)

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

Install Dependencies

The wizard installs required packages:

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

Starting Kortix

After installation, use the service manager:

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

# 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
Docker 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.

# 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:

Add/Update API Keys - Modify existing configuration
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:

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

Production Checklist

Environment Variables

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

Database Security

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

Network Security

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

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 packagesSolution:

# 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 installedSolution:

# 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 portsSolution:

# 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 SupabaseSolution:

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 errorsSolution:

# 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 backendSolution:

# 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:

# 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.

Get Started

Core Concepts

Building Agents

Agent Capabilities

Tools & Extensions

Platform Features

Self-Hosting

Self-Hosted Installation

Overview

System Requirements

Hardware

Software

Installation Methods

Docker Setup

Manual Setup

Step-by-Step Installation

Starting Kortix

Service Manager Features

Monitoring and Logs

Updating Configuration

Architecture Deep Dive

1. Backend API (Port 8000)

2. Frontend Dashboard (Port 3000)

3. Agent Runtime

4. Database & Storage

Network Configuration

Default Ports

DNS Configuration

Security Best Practices

Production Checklist

Troubleshooting

Uninstalling

Next Steps

Configuration Guide

Deploy to Production

API Reference

Agent Development

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building Agents

Agent Capabilities

Tools & Extensions

Platform Features

Self-Hosting

​Overview

​System Requirements

Hardware

Software

​Installation Methods

​Docker Setup

​Manual Setup

​Step-by-Step Installation

​Starting Kortix

​Service Manager Features

​Monitoring and Logs

​Updating Configuration

​Architecture Deep Dive

​1. Backend API (Port 8000)

​2. Frontend Dashboard (Port 3000)

​3. Agent Runtime

​4. Database & Storage

​Network Configuration

​Default Ports

​DNS Configuration

​Security Best Practices

​Production Checklist

​Troubleshooting

​Uninstalling

​Next Steps

Configuration Guide

Deploy to Production

API Reference

Agent Development

Build docs developers (and LLMs) love

Overview

System Requirements

Installation Methods

Docker Setup

Manual Setup

Step-by-Step Installation

Starting Kortix

Service Manager Features

Monitoring and Logs

Updating Configuration

Architecture Deep Dive

1. Backend API (Port 8000)

2. Frontend Dashboard (Port 3000)

3. Agent Runtime

4. Database & Storage

Network Configuration

Default Ports

DNS Configuration

Security Best Practices

Production Checklist

Troubleshooting

Uninstalling

Next Steps