Setup Guide

Step-by-step instructions to install and configure Kortix

Prerequisites

Before starting, ensure you have:

• Git installed
• Docker installed and running (check with docker --version)
• For manual setup: Node.js 18+, Python 3.11+, pnpm, and uv

Clone the Repository

First, clone the Kortix repository:

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

Setup Methods

Kortix offers two setup methods. The setup wizard will guide you through choosing one.

Docker Setup

Best for: Production deployments, quick testing, users who prefer containerized environments

Pros:

• Fastest setup
• Isolated environments
• Easy updates and rollbacks
• Consistent across different systems

Cons:

• Limited to cloud Supabase only (local Supabase not supported)
• Slightly higher resource usage

Manual Setup

Best for: Development, customization, debugging

Pros:

• Full control over each service
• Easier to debug and modify
• Better for development workflows
• Lower resource overhead

Cons:

• More complex setup
• Requires managing multiple processes
• Limited to cloud Supabase only

Important: Both setup methods currently only support cloud Supabase. Local Supabase integration is not available due to Docker networking limitations. See GitHub issue #1920 for updates.

Run the Setup Wizard

The interactive setup wizard configures all required services:

python setup.py

What the Wizard Does

The wizard guides you through these steps:

1. Choose Setup Method

   Select between Docker Compose or Manual setup based on your needs.

2. Check Requirements

   Verifies all required tools are installed (Git, Docker, Node.js, etc.).

3. Configure Supabase

   Set up your Supabase project:

   • Project URL
   • Anon key
   • Service role key
   • JWT secret (critical for authentication)
   • Database connection URL

   Find these in your Supabase Dashboard → Project Settings → API

4. Configure Daytona

   Enter your Daytona API key for agent execution environments.

   Get your key from app.daytona.io/keys

5. Select Main LLM Provider

   Choose your primary LLM provider:

   • Anthropic Claude
   • AWS Bedrock
   • Grok via OpenRouter
   • OpenAI via OpenRouter
   • MiniMax via OpenRouter
   • Custom model
6. Configure Optional Services

   Optionally configure:

   • Additional LLM providers
   • Search APIs (Tavily, Firecrawl, Serper, Exa)
   • RapidAPI
   • Webhooks
   • MCP (Model Context Protocol)
7. Configure Composio

   Enter your Composio API key (required for tool integrations).

   Get your key from app.composio.dev/settings/api-keys

8. Write Configuration Files

   The wizard automatically creates:

   • backend/.env - Backend configuration
   • apps/frontend/.env.local - Frontend configuration
   • .setup_progress - Resume data (can be deleted after setup)

The wizard saves progress after each step. If interrupted, just run python setup.py again to resume.

Start Services

After completing the setup wizard, start Kortix:

python start.py

Start Script Options

The start script automatically detects your setup method:

# Interactive mode (shows menu)
python start.py

# Start all services
python start.py start

# Stop all services
python start.py stop

# Show service status
python start.py status

# Restart all services
python start.py restart

# Force start without confirmation
python start.py start -f

Docker Setup

If you chose Docker Compose, services start automatically:

python start.py start

This runs:

• Redis - Message queue and caching (port 6379)
• Backend - API server (port 8000)
• Frontend - Web interface (port 3000)

Docker Commands

# View logs
docker compose logs -f

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

# Check service status
docker compose ps

# Stop all services
python start.py stop
# or
docker compose down

# Stop and remove volumes
docker compose down -v

Manual Setup

If you chose Manual setup, the start script launches services in the background:

python start.py start

This starts:

1. Redis (Docker container)
2. Backend (native process, logged to backend.log)
3. Frontend (native process, logged to frontend.log)

Manual Commands

View logs:

# 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

Start services individually:

# Start Redis
docker compose up -d redis

# Start Backend (in a terminal)
cd backend && uv run api.py

# Start Frontend (in another terminal)
cd apps/frontend && pnpm run dev

On macOS/Linux, background processes are logged to files. On Windows, services open in separate command windows.

Access Kortix

Once all services are running:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Verify Installation

1. Check Service Status

   python start.py status
   

   All services should show as “Running”.

2. Access Frontend

   Open http://localhost:3000 in your browser.

3. Create Account

   Sign up with your email. Supabase handles authentication.

4. Test Agent

   Try the Kortix Super Worker agent to verify everything works.

Update Configuration

To add or update API keys after initial setup:

python setup.py

The wizard detects existing configuration and offers:

• Add/Update API Keys - Configure additional LLM providers, search APIs, etc.
• Clear setup and start fresh - Remove all configuration and restart

Next Steps

Configuration

Learn about all available configuration options

Deployment

Deploy to production environments