Skip to main content

​
Prerequisites

Before you begin, ensure you have:

Python 3.11+

Required for running the Kortix backend

Node.js 18+

Required for the frontend dashboard

Docker

Required for agent runtime and Redis

Git

For cloning the repository

​
Get Your Kortix Platform Running

1

Clone the Repository

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

Run the Setup Wizard

The automated setup wizard will guide you through configuring all required services:
python setup.py
The wizard will:
  • Detect your system requirements (Docker, Python, Node.js)
  • Let you choose between Docker or Manual setup
  • Configure Supabase (cloud or local)
  • Set up LLM provider API keys (Anthropic, OpenAI, etc.)
  • Configure optional integrations (Tavily, Firecrawl, Composio)
  • Generate environment files automatically
  • Create database tables and schemas
Progress is automatically saved, so you can resume if interrupted. Just run python setup.py again.
3

Start the Platform

Use the interactive service manager:
python start.py
Or use specific commands:
python start.py start
The service manager automatically detects your setup method (Docker or Manual) and manages services accordingly.
4

Access Kortix

Once services are running, open your browser:
http://localhost:3000
You’ll see:
  • Frontend Dashboard - http://localhost:3000
  • Backend API - http://localhost:8000
  • API Documentation - http://localhost:8000/docs

​
Create Your First Agent

1

Navigate to Agent Builder

In the Kortix dashboard, click on “Create Agent” or navigate to the Agent Builder.
2

Configure Your Agent

Provide basic configuration:
  • Name: “My First Agent”
  • System Prompt: “You are a helpful AI assistant that can research topics and provide detailed answers.”
  • Allowed Tools: Select tools like web search, file operations, etc.
  • Model: Choose your LLM provider (configured in setup)
3

Start a Conversation

Click “Create” and start chatting with your agent:
You: "Research the latest developments in AI agents and summarize the key trends"
Your agent will:
  • Search the web for relevant information
  • Analyze and synthesize findings
  • Provide a comprehensive summary

​
Using the Python SDK

You can also interact with Kortix programmatically using the Python SDK:
1

Install the SDK

pip install "kortix @ git+https://github.com/kortix-ai/suna.git@main#subdirectory=sdk"
Or with uv:
uv add "kortix @ git+https://github.com/kortix-ai/suna.git@main#subdirectory=sdk"
2

Get Your API Key

Navigate to Settings → API Keys in the Kortix dashboard and create a new API key.
Keep your API key secure and never commit it to version control.
3

Create and Run an Agent

import asyncio
from kortix import kortix

async def main():
    # Initialize the client
    client = kortix.Kortix(
        api_key="your-api-key",
        base_url="http://localhost:8000/v1"
    )

    # Create an agent
    agent = await client.Agent.create(
        name="Research Assistant",
        system_prompt="You are a helpful research assistant.",
        allowed_tools=["web_search", "file_operations"]
    )

    # Create a conversation thread
    thread = await client.Thread.create()

    # Run the agent
    run = await agent.run(
        "What are the top 3 AI trends in 2026?",
        thread
    )

    # Stream the response
    stream = await run.get_stream()
    async for chunk in stream:
        print(chunk, end="")

if __name__ == "__main__":
    asyncio.run(main())

​
Viewing Logs

Monitor your platform in real-time: 
# 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

​
Adding More API Keys

After initial setup, you can add or update API keys: 
python setup.py
The wizard will allow you to:
  • Add/Update API Keys - Configure additional LLM providers, search APIs, and integrations
  • Clear setup and start fresh - Remove all configuration and restart

​
Next Steps

SDK Reference

Deep dive into the Kortix SDK capabilities

Agent Configuration

Learn advanced agent customization

MCP Tools

Extend agents with Model Context Protocol tools

API Reference

Explore the complete REST API

​
Troubleshooting

  1. Check Docker is running: docker ps
  2. Verify ports 3000 and 8000 are available
  3. Review logs: python start.py status
  4. Try restarting: python start.py restart
  • For cloud Supabase: Verify your credentials in .env
  • For local Supabase: Ensure it’s running with npx supabase status
  • Check network connectivity and firewall settings
  • Verify LLM provider API keys are correct
  • Check backend logs for errors
  • Ensure you have sufficient API credits with your LLM provider
Run the setup wizard again:
python setup.py
It will detect missing configuration and guide you through fixes.
For additional help, join our Discord community or check the GitHub issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us