> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kortix-ai/suna/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get from account setup to your first agent interaction in minutes

## Prerequisites

Before you begin, ensure you have:

<CardGroup cols={2}>
  <Card title="Python 3.11+" icon="python">
    Required for running the Kortix backend
  </Card>

  <Card title="Node.js 18+" icon="node">
    Required for the frontend dashboard
  </Card>

  <Card title="Docker" icon="docker">
    Required for agent runtime and Redis
  </Card>

  <Card title="Git" icon="git">
    For cloning the repository
  </Card>
</CardGroup>

## Get Your Kortix Platform Running

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/kortix-ai/suna.git
    cd suna
    ```
  </Step>

  <Step title="Run the Setup Wizard">
    The automated setup wizard will guide you through configuring all required services:

    ```bash theme={null}
    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

    <Note>
      Progress is automatically saved, so you can resume if interrupted. Just run `python setup.py` again.
    </Note>
  </Step>

  <Step title="Start the Platform">
    Use the interactive service manager:

    ```bash theme={null}
    python start.py
    ```

    Or use specific commands:

    <CodeGroup>
      ```bash Start All Services theme={null}
      python start.py start
      ```

      ```bash Stop All Services theme={null}
      python start.py stop
      ```

      ```bash Check Status theme={null}
      python start.py status
      ```

      ```bash Restart Services theme={null}
      python start.py restart
      ```
    </CodeGroup>

    <Info>
      The service manager automatically detects your setup method (Docker or Manual) and manages services accordingly.
    </Info>
  </Step>

  <Step title="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`
  </Step>
</Steps>

## Create Your First Agent

<Steps>
  <Step title="Navigate to Agent Builder">
    In the Kortix dashboard, click on **"Create Agent"** or navigate to the Agent Builder.
  </Step>

  <Step title="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)
  </Step>

  <Step title="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
  </Step>
</Steps>

## Using the Python SDK

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

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    pip install "kortix @ git+https://github.com/kortix-ai/suna.git@main#subdirectory=sdk"
    ```

    Or with uv:

    ```bash theme={null}
    uv add "kortix @ git+https://github.com/kortix-ai/suna.git@main#subdirectory=sdk"
    ```
  </Step>

  <Step title="Get Your API Key">
    Navigate to **Settings → API Keys** in the Kortix dashboard and create a new API key.

    <Warning>
      Keep your API key secure and never commit it to version control.
    </Warning>
  </Step>

  <Step title="Create and Run an Agent">
    ```python theme={null}
    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())
    ```
  </Step>
</Steps>

## Viewing Logs

Monitor your platform in real-time:

<CodeGroup>
  ```bash Manual Setup theme={null}
  # 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
  ```

  ```bash Docker Setup theme={null}
  # View all service logs
  docker compose logs -f

  # View specific service
  docker compose logs -f backend
  docker compose logs -f frontend
  ```
</CodeGroup>

## Adding More API Keys

After initial setup, you can add or update API keys:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="SDK Reference" icon="code" href="/sdk/overview">
    Deep dive into the Kortix SDK capabilities
  </Card>

  <Card title="Agent Configuration" icon="sliders" href="/agents/agent-builder">
    Learn advanced agent customization
  </Card>

  <Card title="MCP Tools" icon="puzzle-piece" href="/tools/mcp-integration">
    Extend agents with Model Context Protocol tools
  </Card>

  <Card title="API Reference" icon="book" href="/api/introduction">
    Explore the complete REST API
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Services won't start">
    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`
  </Accordion>

  <Accordion title="Database connection errors">
    * 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
  </Accordion>

  <Accordion title="Agent not responding">
    * Verify LLM provider API keys are correct
    * Check backend logs for errors
    * Ensure you have sufficient API credits with your LLM provider
  </Accordion>

  <Accordion title="Docker Compose issues">
    Run the setup wizard again:

    ```bash theme={null}
    python setup.py
    ```

    It will detect missing configuration and guide you through fixes.
  </Accordion>
</AccordionGroup>

<Tip>
  For additional help, join our [Discord community](https://discord.com/invite/RvFhXUdZ9H) or check the [GitHub issues](https://github.com/kortix-ai/suna/issues).
</Tip>