Suna AI: Open Source General AI Agent Guide (2026)

Suna AI: Open Source General AI Agent Guide (2026)

Suna AI is an open-source general-purpose AI agent that can browse the web, write and execute code, manage files, and interact with external services -- all through natural language instructions. Think of it as an AI assistant that can actually do things on your computer, not just chat about them.

This guide covers everything you need to know about Suna AI in 2026: what it can do, how to set it up, and how it compares to alternatives like OpenAI's Operator, Claude Code, and AutoGPT.

What Is Suna AI?

Suna AI is an open-source AI agent built by the Kortix team. Unlike chatbots that only generate text responses, Suna is an agentic AI -- it can take actions, use tools, and complete multi-step tasks autonomously.

Core Capabilities

Capability	Description
Web browsing	Navigate websites, fill forms, extract data, take screenshots
Code execution	Write, run, and debug code in Python, JavaScript, and more
File management	Create, read, edit, and organize files and folders
Data extraction	Scrape websites, parse PDFs, extract structured data
API interaction	Make HTTP requests, interact with REST APIs
Document creation	Generate reports, spreadsheets, presentations
Research	Multi-step web research with source compilation

Architecture Overview

Suna AI uses a modular architecture:

User Input (Natural Language)
    ↓
Planning Module (breaks task into steps)
    ↓
Tool Selection (chooses appropriate tools)
    ↓
Execution Engine (runs tools in sandboxed environment)
    ↓
Result Compilation (aggregates outputs)
    ↓
User Output (formatted response + artifacts)

The agent runs tasks in a sandboxed Docker environment, which means it cannot accidentally damage your system. All browser interactions happen in a headless Chromium instance.

How to Set Up Suna AI

Prerequisites

• Docker and Docker Compose installed
• Node.js 18+ (for the frontend)
• Python 3.10+ (for backend components)
• At least 8GB RAM
• An LLM API key (OpenAI, Anthropic, or compatible)

Installation Steps

Step 1: Clone the repository

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

Step 2: Configure environment variables

cp .env.example .env

Edit the .env file with your API keys:

# LLM Provider (choose one)
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# Optional: Custom LLM endpoint (for local models)
# LLM_BASE_URL=http://localhost:11434/v1
# LLM_MODEL=llama3.1:70b

# Browser configuration
BROWSER_HEADLESS=true
BROWSER_TIMEOUT=30000

# Sandbox configuration
SANDBOX_MEMORY_LIMIT=4g
SANDBOX_CPU_LIMIT=2

Step 3: Start with Docker Compose

docker-compose up -d

Step 4: Access the web interface

Open http://localhost:3000 in your browser. You should see the Suna AI dashboard.

Self-Hosting vs Hosted Version

Option	Cost	Setup	Maintenance
Self-hosted (Docker)	LLM API costs only	15-30 minutes	You manage updates
Kortix hosted	Free tier + paid plans	Instant	Managed for you

The hosted version at suna.so offers a free tier with limited usage, which is the fastest way to try Suna without any setup.

Practical Usage Examples

Example 1: Research and Report Generation

Prompt: "Research the top 5 AI video generation APIs in 2026.
Compare their pricing, features, and quality.
Create a detailed markdown report with tables."

Suna will:

1. Open a browser and search for AI video generation APIs
2. Visit multiple provider websites (Hypereal AI, Runway, Kling, etc.)
3. Extract pricing and feature information
4. Compile everything into a structured markdown report
5. Save the report as a downloadable file

Example 2: Data Scraping and Analysis

Prompt: "Go to the Hacker News front page, scrape the top 30 posts,
and create a CSV with title, URL, points, and comment count.
Then analyze which topics are trending."

Suna executes this as a multi-step task:

# Suna generates and runs code like this internally:
import requests
from bs4 import BeautifulSoup
import pandas as pd

response = requests.get("https://news.ycombinator.com")
soup = BeautifulSoup(response.text, "html.parser")

posts = []
for item in soup.select(".athing"):
    title_el = item.select_one(".titleline > a")
    subtext = item.find_next_sibling("tr").select_one(".subtext")
    # ... extraction logic
    posts.append({"title": title, "url": url, "points": points})

df = pd.DataFrame(posts)
df.to_csv("hn_top_posts.csv", index=False)

Example 3: Automated Form Filling

Prompt: "Go to [website], fill out the contact form with the following
information: Name: John Smith, Email: john@example.com,
Message: 'Interested in enterprise pricing'"

Suna uses its browser tool to navigate to the page, locate form fields, fill them in, and submit.

Example 4: Code Project Scaffolding

Prompt: "Create a new Next.js project with TypeScript, Tailwind CSS,
and shadcn/ui. Add a landing page with a hero section, features grid,
and pricing table. Use the dark theme."

Suna will create the entire project structure, install dependencies, and write the component code.

Suna AI vs Other AI Agents

Feature	Suna AI	OpenAI Operator	Claude Code	AutoGPT	Devin
Open source	Yes	No	No	Yes	No
Web browsing	Yes	Yes	No	Yes	Limited
Code execution	Yes	No	Yes	Yes	Yes
File management	Yes	Limited	Yes	Yes	Yes
Self-hostable	Yes	No	No	Yes	No
LLM flexibility	Any provider	OpenAI only	Anthropic only	Any provider	Proprietary
Cost	API costs only	$200/mo (Pro)	$100-200/mo	API costs	$500/mo
Sandbox security	Docker	Cloud sandbox	Local	Docker	Cloud
Ease of setup	Moderate	Easy (hosted)	Easy (CLI)	Moderate	Easy (hosted)

When to Choose Suna AI

• You want full control: Self-hosting means your data stays on your infrastructure
• You need web browsing + code execution: Suna combines both in a single agent
• You want LLM flexibility: Use OpenAI, Anthropic, local models, or any OpenAI-compatible endpoint
• Budget-conscious: No subscription fee -- you only pay for LLM API calls

When to Choose Alternatives

• Pure coding tasks: Claude Code is more refined for software development workflows
• Web automation only: OpenAI Operator is more polished for browser-based tasks
• Enterprise needs: Devin offers better team collaboration features (at a premium)

Advanced Configuration

Using Local LLMs with Suna

You can run Suna with local models via Ollama to eliminate API costs entirely:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a capable model
ollama pull llama3.1:70b

# Configure Suna to use local model
# In .env:
LLM_BASE_URL=http://host.docker.internal:11434/v1
LLM_MODEL=llama3.1:70b
LLM_API_KEY=ollama  # Ollama doesn't need a real key

Note: Local models work but are significantly less capable than GPT-4o or Claude Opus 4 for complex agentic tasks. Expect more errors and retries with smaller models.

Custom Tool Development

Suna supports custom tools through its plugin system:

# custom_tools/my_tool.py
from suna.tools.base import BaseTool

class MyCustomTool(BaseTool):
    name = "my_custom_tool"
    description = "Does something specific for my workflow"

    def execute(self, params: dict) -> str:
        # Your custom logic here
        result = self.process(params["input"])
        return f"Processed: {result}"

Register the tool in the configuration:

# config/tools.yaml
custom_tools:
  - name: my_custom_tool
    module: custom_tools.my_tool
    enabled: true

Performance Tips

1. Use specific prompts: Vague instructions lead to more LLM calls and higher costs
2. Break complex tasks into steps: Guide the agent through multi-step workflows
3. Set timeouts: Configure BROWSER_TIMEOUT to prevent hanging on slow websites
4. Monitor token usage: Check the dashboard for API cost tracking
5. Use caching: Enable response caching for repetitive tasks

Common Issues and Fixes

Issue	Cause	Fix
Browser actions failing	Timeout too short	Increase BROWSER_TIMEOUT
High API costs	Using GPT-4o for simple tasks	Switch to GPT-4o-mini for lightweight tasks
Docker memory errors	Insufficient resources	Increase SANDBOX_MEMORY_LIMIT
Authentication failures	Expired API key	Regenerate and update .env
Slow performance	Large model on weak hardware	Use hosted version or cloud GPU

Frequently Asked Questions

Is Suna AI free?

The software is free and open source (Apache 2.0 license). You pay only for LLM API calls. Using local models via Ollama makes it completely free, though with reduced capability.

Can Suna AI replace a developer?

No. Suna is a productivity tool, not a replacement. It excels at automating repetitive tasks, research, and scaffolding, but complex software engineering still requires human judgment.

Is it safe to give Suna access to my accounts?

Exercise caution. While Suna runs in a sandboxed environment, you should avoid providing credentials to sensitive accounts. Use dedicated test accounts or API keys with limited permissions.

How does Suna compare to ChatGPT with browsing?

Suna is significantly more capable. ChatGPT's browsing is limited to read-only web access, while Suna can interact with websites, fill forms, execute code, and manage files.

Conclusion

Suna AI represents a significant step forward in open-source AI agents. Its combination of web browsing, code execution, and file management makes it a versatile tool for automation and research tasks.

For creators and developers who need to integrate AI generation capabilities (images, video, audio) into their workflows, Hypereal AI complements Suna nicely. While Suna handles task automation and research, Hypereal AI provides the media generation backbone with models like Sora 2, Kling 2.1, Flux, and more -- all accessible through a single API.