Suna AI: the Open Source General AI Agent

The field of artificial intelligence is increasingly moving towards agents that can do more than just process information – they can act. Suna AI emerges in this space as a compelling open-source generalist AI agent, designed to function as a digital companion capable of understanding natural language instructions and executing complex, real-world tasks directly on your behalf. Developed by Kortix AI and released under the permissive Apache 2.0 license, Suna differentiates itself by combining a powerful suite of tools with a conversational interface, aiming to bridge the gap between user intent and tangible digital action.

Unlike specialized AI tools, Suna's strength lies in its versatility. It's built to orchestrate various capabilities – from browsing the web and managing files to executing code and interacting with APIs – all driven by your conversational prompts. This article provides an overview of Suna's core capabilities and architecture, followed by a detailed, step-by-step tutorial on how to set up and run your own instance locally, empowering you to leverage this powerful AI agent within your own environment.

💡

Want a great API Testing tool that generates beautiful API Documentation?

Want an integrated, All-in-One platform for your Developer Team to work together with maximum productivity?

Apidog delivers all your demans, and replaces Postman at a much more affordable price!

button

What is Suna AI and How Does Suna AI Work?

To understand what Suna can do, it's essential to grasp the tools it wields. These capabilities allow it to interact with the digital world much like a human user, but automated and driven by AI.

Browser Automation (via Playwright): Suna can launch and control a web browser instance within its secure environment. This means it can navigate to specific URLs, log into websites (if provided credentials securely), click buttons, fill out forms, scroll pages, and, crucially, extract data directly from web page content. This capability unlocks the vast amount of information and functionality available on the web for automation.
File Management: The agent isn't limited to just web data. It possesses the ability to interact with a file system within its sandboxed environment. This includes creating new files (like reports or data exports), reading existing documents, editing their content, and organizing files into directories. This is vital for tasks that involve generating outputs or processing local data.
Web Crawling & Enhanced Search: Beyond single-page browsing, Suna can systematically crawl websites (following links) to gather comprehensive information. It can also integrate with dedicated search APIs (like the optional Tavily integration) to perform more sophisticated, targeted information retrieval than standard search engine use, allowing for deeper research capabilities.
Command-Line Execution: Within its secure Docker container, Suna has the ability to execute shell commands. This powerful feature allows it to run scripts, utilize other command-line utilities, interact with system resources (within the container's limits), and potentially automate tasks like software builds or deployments if configured appropriately. Security is paramount here, handled by the isolated environment.
API Integration (via RapidAPI & Direct Calls): Suna can make calls to external Application Programming Interfaces (APIs). This allows it to connect with a vast ecosystem of third-party services. The documentation highlights optional RapidAPI integration, enabling access to various data providers (e.g., for LinkedIn data, financial information, etc.), but it can also be configured to interact with other RESTful APIs directly, vastly extending its data-gathering and action-taking potential.
Code Interpretation: Suna includes the ability to execute code snippets (primarily Python) within its secure environment. This is not just for running existing scripts but allows the agent to dynamically generate and run code to perform complex calculations, data analysis, custom logic processing, or transformations that go beyond the capabilities of its other tools.

The true power of Suna lies in the AI's ability to select and sequence these tools appropriately based on the user's request. A single instruction might trigger a workflow involving searching the web, extracting data, processing it with interpreted code, formatting the result into a file, and saving it – all managed by the agent.

Suna's Architecture: The Components Involved

Understanding the setup process requires a basic grasp of Suna's main architectural components:

Backend API (Python/FastAPI): The core logic resides here. It manages user requests, maintains conversation state, orchestrates the agent's tool usage, and handles communication with the chosen Large Language Model (LLM) via LiteLLM (providing flexibility with providers like OpenAI and Anthropic).
Frontend (Next.js/React): This is the user-facing web application. It provides the chat interface for interacting with Suna, displays results, and includes dashboard elements for monitoring agent activity.
Agent Docker Environment (via Daytona): Security and isolation are critical. Each agent task runs within a dedicated Docker container managed by Daytona. This sandbox contains all the necessary tools (browser, code interpreter, file system access) and prevents the agent from interfering with the host system.
Supabase Database (PostgreSQL): Handles all data persistence needs, including user accounts and authentication, conversation history, storage for files generated by the agent, agent state tracking, and potentially analytics.

These components work together, communicating via APIs, to deliver the Suna experience. The self-hosting setup involves configuring and running these interconnected parts.

How to Set up Suna AI

Running Suna yourself provides maximum control and privacy. The following steps guide you through the setup process:

Phase 1: Gathering Prerequisites

Before installing Suna, you need several external services and credentials:

Supabase Project:

Sign up or log in at supabase.com and create a new project.
Navigate to your project's Settings > API. Carefully copy your Project URL, anon public key, and service_role secret key.
Install the Supabase CLI: Follow instructions at supabase.com/docs/guides/cli.

Redis Database:

Option 1 (Cloud - Recommended): Use a service like Upstash (offers a free tier). Create a database and record its Host/Endpoint, Port, Password, and note if SSL/TLS is required (usually yes).
Option 2 (Local): Install Redis locally (e.g., brew install redis on macOS, sudo apt install redis-server on Debian/Ubuntu, or via Docker/WSL on Windows). Note the Host (localhost), Port (usually 6379), Password (usually none), and SSL setting (False).

Daytona Account & Image Configuration:

Sign up at daytona.io.
Go to Settings > API Keys and generate a new API Key. Copy it.
Go to the Images section. Click Add Image.
Image Name: adamcohenhillel/kortix-suna:0.0.20
Entrypoint: /usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf
Save this image configuration.

LLM API Key:

Choose between OpenAI (platform.openai.com) or Anthropic (console.anthropic.com). Obtain an API Key from your chosen provider.
Note the specific Model Identifier you plan to use (e.g., gpt-4o, anthropic/claude-3-5-sonnet-latest).

(Optional) Tavily API Key: For better search results. Get a key from Tavily AI.

(Optional) RapidAPI Key: If you intend to use pre-built integrations needing it (like specific web scrapers).

Get a key from rapidapi.com.
Remember to subscribe to the specific APIs (e.g., LinkedIn scraper) on the RapidAPI marketplace that the Suna tools might use. Check the backend/agent/tools/data_providers/ directory for relevant tool code and their required API base URLs.

Phase 2: Installation and Configuration

Now, configure the Suna application components:

Clone the Repository:

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

Configure Backend (.env):

cd backend
cp .env.example .env (or create .env if the example is missing).
Edit .env with the credentials from Phase 1:

NEXT_PUBLIC_URL="http://localhost:3000" # Or your frontend URL if different

# Supabase
SUPABASE_URL=YOUR_SUPABASE_URL
SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY=YOUR_SUPABASE_SERVICE_ROLE_KEY

# Redis
REDIS_HOST=YOUR_REDIS_HOST
REDIS_PORT=YOUR_REDIS_PORT
REDIS_PASSWORD=YOUR_REDIS_PASSWORD # Leave blank if none
REDIS_SSL=True # Or False for local non-SSL Redis

# Daytona
DAYTONA_API_KEY=YOUR_DAYTONA_API_KEY
DAYTONA_SERVER_URL="https://app.daytona.io/api"
DAYTONA_TARGET="us" # Or your region

# --- LLM Configuration (FILL ONLY ONE SET) ---
# Anthropic Example:
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
MODEL_TO_USE="anthropic/claude-3-5-sonnet-latest" # Or other Claude model
OPENAI_API_KEY=
# OpenAI Example:
# ANTHROPIC_API_KEY=
# OPENAI_API_KEY=YOUR_OPENAI_API_KEY
# MODEL_TO_USE="gpt-4o" # Or other OpenAI model
# -----------------------------------------

# Optional
TAVILY_API_KEY=YOUR_TAVILY_API_KEY # Optional
RAPID_API_KEY=YOUR_RAPID_API_KEY # Optional

Critical: Only provide keys for one LLM provider (either Anthropic or OpenAI).

Set up Supabase Database Schema:

Ensure you are in the backend directory.
Log in: supabase login
Link project: supabase link --project-ref YOUR_PROJECT_REF_ID (Get ID from Supabase dashboard).
Apply migrations: supabase db push
Verify Schema: Go to your Supabase project dashboard -> Project Settings -> API -> Schema section under "Config". Make sure basejump is listed in "Exposed schemas". Add it if missing and save.

Configure Frontend (.env.local):

cd ../frontend
cp .env.example .env.local (or create .env.local).
Edit .env.local:

NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL # Same as in backend .env
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY # Same as in backend .env
NEXT_PUBLIC_BACKEND_URL="http://localhost:8000/api" # Default backend location
NEXT_PUBLIC_URL="http://localhost:3000" # Default frontend location

Install Dependencies:

Frontend (Node.js/npm):

# In frontend directory
npm install

Backend (Python 3.11):

# In backend directory (use a virtual environment!)
# python -m venv venv
# source venv/bin/activate  OR .\venv\Scripts\activate (Windows)
pip install -r requirements.txt

Phase 3: Running Suna

Start Backend Service:

Open a terminal.
Navigate to path/to/suna/backend.
If using a virtual environment, activate it (source venv/bin/activate).
Run: python api.py
Look for confirmation that the server is running (likely on port 8000).

Start Frontend Service:

Open a second terminal.
Navigate to path/to/suna/frontend.
Run: npm run dev
Look for confirmation that the server is running (likely on port 3000).

Access Your Suna Instance:

Open a web browser and go to http://localhost:3000.
Use the Sign Up option to create your user account (powered by Supabase Auth).
Log in and begin instructing your self-hosted Suna agent.

Conclusion

Suna AI represents a practical step towards autonomous AI agents capable of executing tasks in the digital realm. Its open-source nature, combined with a powerful toolkit and a modular architecture, makes it an attractive option for developers and users seeking a customizable, self-hostable AI assistant. By following the detailed setup process outlined above, you can deploy your own instance of Suna, granting you a conversational interface to automate browsing, file manipulation, data gathering, code execution, and more, all within an environment you control. While setting it up requires careful attention to its multiple components, the result is a versatile AI agent ready to act on your behalf.

💡

button