Suna

Local-first agent runtime with isolated subtasks, layered Guard, memory, Skills, MCP, and a terminal UI.

Suna is released under the PolyForm Noncommercial License — free for personal and non-commercial use.

中文 README · Documentation · Subtasks

Suna is not just another terminal chat agent. It is a local agent runtime where a main agent can delegate work to isolated subtasks with different models, explicit context, selected images, and a per-task tool whitelist — while risky actions still go through a layered Guard.

The built-in TUI is the default client. Third-party desktop apps, IDE extensions, local web UIs, or scripts can connect to the same daemon through TCP JSON-RPC/NDJSON after suna serve --json.

A real Suna session with streaming output, tool activity, Guard decisions, and usage status.

Suna is under active development. If an upgrade breaks local state, update to the latest release first and back up important data before removing .db files under the Suna data directory.

Why Suna?

Isolated Subtasks

Most terminal agents run one model with one shared context and one shared toolset. Suna lets the main agent create bounded workers at runtime:

• choose a different model for a specific subtask;
• pass only explicit task/context/images;
• grant only selected tools, or no tools at all;
• keep user memory and main conversation history out of the subtask by default;
• return structured status, result text, error, and side-effect disclosure to the main agent.

This makes delegation explainable and auditable instead of becoming an uncontrolled second agent.

An isolated subtask keeps its task timeline, tool activity, and result visible to the main session.

Guard: hard rules + mode policy

Suna's Guard is a static safety layer with three layers. Hard rules (systemically dangerous commands, blocked patterns, workspace boundaries, sensitive files) are always enforced in every mode. A precise read-only analysis then decides what needs review: smart mode lets an LLM review exec calls as a binary approve/reject gate (it judges the operation's own risk, not user intent), ask mode asks the user for every non-read-only action, auto trusts the model beyond hard rules, and readonly rejects anything that changes state.

Runtime-first architecture

Suna separates UI from a shared local runtime. The daemon owns the model catalog, providers, tools, Guard, memory, attachments, and persistent session state; each session owns its selected model and working conversation state:

Built-in TUI / third-party UI / script
        ↓ JSON-RPC over local or TCP transport
Daemon / shared runtime
    ├─ model catalog, providers, tools, Guard, memory, Skills, MCP
    └─ sessions
        ├─ selected model + conversation / working state
        ├─ attachments, usage, and run lifecycle
        └─ isolated subtasks
             ├─ explicit model
             ├─ explicit context
             └─ explicit tool permissions

The built-in TUI is only one client. A default model is used when creating a new conversation; each existing session keeps its own selected model, including after restart or when another session changes model.

Who is Suna for?

Suna is for people who want a local AI workbench that can work with files, documents, code, commands, APIs, images, and custom tools — while keeping risky actions reviewable.

It may fit you if you want:

• a terminal AI assistant that understands local context;
• safer file and command operations with Guard;
• isolated subtasks instead of one giant shared context;
• a runtime that can be reused by Web UIs, IDEs, desktop apps, or scripts;
• memory, Skills, MCP, and tools under your own control.

Common workflows

Use Suna to:

• organize notes, meeting records, and research material;
• read a local folder and summarize what matters;
• compare options and ask a subtask for an independent second opinion;
• clean up documents or config files with confirmation before writing;
• run local commands for diagnostics, tests, builds, and automation;
• call HTTP APIs and turn responses into readable summaries;
• create reusable Skills for repeated workflows;
• connect external tools through MCP or third-party clients through the TCP daemon.

What makes Suna different?

Capability	Typical terminal agent	Suna
Model choice	One active model per run	Each session keeps its selected model; subtasks can explicitly use another configured model
Subagent context	Shared or implicit	Explicit, isolated context only
Tool permissions	Usually global	Per-subtask tool whitelist
User memory	Often mixed into the whole context	Lightweight profile memory near the latest user input
Safety	Confirm, auto, or coarse allowlist	Hard rules + read-only analysis + mode policy (smart/ask/auto/readonly)
Skill lifecycle	Prompt/file injection	Static check, optional LLM review, then user confirmation
UI architecture	CLI/TUI app	Local daemon/runtime plus protocol plus TUI client
Third-party UI	Usually not a stable boundary	suna serve --json with JSON-RPC/NDJSON

Install

Download a prebuilt binary from GitHub Releases:

• macOS Apple Silicon: suna-darwin-arm64.zip
• macOS Intel: suna-darwin-amd64.zip
• Linux x86_64: suna-linux-amd64.tar.gz
• Linux arm64: suna-linux-arm64.tar.gz
• Windows x86_64: suna-windows-amd64.zip

Put suna (or suna.exe on Windows) on your PATH, then run:

suna

If you have Go installed, you can also install from source:

go install github.com/alanchenchen/suna@latest
suna

Make sure your Go bin directory is on PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Do not use go run . to launch Suna. The daemon/TUI process manager depends on a stable executable path.

Update

Quit the TUI, then run:

suna update

update checks the latest release, shows release notes, downloads the matching asset, verifies checksums, and replaces the current binary after confirmation.

If the daemon is still running, stop it first:

suna stop

First run

1. Start suna.
2. Open Config / Setup if no model is configured.
3. Add a model connection.
4. Choose a provider protocol:
   • OpenAI: OpenAI Responses API.
   • Anthropic: Anthropic Messages API.
   • OpenAI Compatible: OpenAI Chat Completions compatible providers or gateways.
5. Fill in model name, endpoint, API key, context_window, max_output_tokens, and optional capability labels.
6. Set it as the default model for new conversations, then start a new conversation.

You can change most settings from the TUI with /config. context_window and max_output_tokens must match the real limits of your model provider. strengths tell the main agent what a model is good at. subtask_for optionally controls which session models may see a model as a subtask candidate.

/model changes only the current conversation. The default model in Config is used only for conversations created afterwards.

Themes can be changed from Config → General → Theme. Suna ships a single built-in default theme that adapts to your terminal background, and reads custom themes from ~/.suna/themes/*.toml (the file name is the theme name). See Themes for how to write and share custom themes, or the generated ~/.suna/themes/README.md for the field reference and templates.

Try these prompts

These prompts are intentionally simple. They are meant to show how Suna delegates work, limits tool access, and asks before risky actions.

1. Get a second opinion

I need to decide between two options. First, ask a subtask to give an independent second opinion without using any tools. Then give me your final recommendation.

You should see a spawn tool call where the subtask has no tools and only receives the context the main agent explicitly passes to it.

2. Explore local files safely

Help me understand the documents in this folder. You can ask a read-only subtask to look around with listdir, readfile, and search, then summarize the important points for me.

You should see the main agent grant only read/search tools to the subtask and keep final judgment in the main conversation.

3. Make a small change with confirmation

Please clean up this note and save the improved version. Before writing anything, tell me what you plan to change and let me confirm it.

You should see file edits go through Suna's Guard instead of being silently executed.

What can Suna do?

Organize notes, meeting records, and research material
Compare options and turn rough ideas into a practical plan
Read a local folder and summarize what matters
Analyze screenshots or pasted images
Call HTTP APIs and turn responses into readable summaries
Check documents, configs, or scripts for conflicts and risks
Modify files with exact edits and explain the impact
Run commands for diagnostics, tests, builds, and automation
Search local files by path, symbol-like entries, or content
Use MCP tools from configured stdio servers
Create, review, and enable Skills
Compact long sessions into Session State
Delegate bounded subtasks to other configured models

Action tools such as writing files, running commands, filesystem operations, and HTTP write requests go through Guard.

Built-in tools

Category	Tool	Purpose
Perception	readfile	Read files by line range, tail, or base64
Perception	listdir	List directories with recursion, pagination, include/exclude filters
Perception	search	Structured local search across paths, headings/symbol-like entries, and content
Perception	read_image	Load an image (local path, URL, or historical attachment ref) so a multimodal model can see it; historical [image: ...] summaries carry a source= value that can be passed here to re-read
Action	exec	Run or manage bounded shell commands; long-running work can be started explicitly in the background and queried or stopped by job ID
Action	writefile	Create, overwrite, or append files
Action	editfile	Atomically apply exact text replacements to a single file
Action	filesystem	stat, mkdir, move, copy, or remove paths
Action	http	Send HTTP requests; read methods are lower risk than write methods

Tools are exposed through a stable provider system. Guard decisions are handled by the Agent, not by UI code or ad-hoc tool wrappers.

TUI quick reference

Common keys:

Enter              Send / confirm
Shift+Enter        Newline
Ctrl+J             Newline
Esc                Cancel run, go back, or close overlay
↑ / ↓             Recall previous / next input when the composer is empty
Ctrl+T             Expand or collapse the tool block in view
Ctrl+R             Toggle reasoning detail
?                  Toggle help
PgUp / PgDn        Scroll; manual scrolling pauses follow
Home               View the start of the current long response when the composer is empty
End                Return to latest content and resume follow
Ctrl+V             Paste text; if no terminal text is provided and clipboard has an image, attach image
Ctrl+C             Quit

Common slash commands:

/new              Replace the current idle exclusive session with a new one
/sessions         Join active sessions elsewhere or remove idle ones
/model            Open model picker for the current conversation
/model <ref>      Switch the current conversation model, e.g. /model openai/gpt-4o-mini
/memory           View user profile memory
/mcp              Open MCP panel
/skills           Open Skill panel
/compact          Manually compact current context
/config           Open configuration
/help             Open help

Unknown /text input is sent as a normal message.

Safety boundary

Guard modes:

smart     Default. Read-only calls pass; exec calls are reviewed by an LLM (approve/reject); other writes pass
ask       Read-only calls pass; every non-read-only action asks for confirmation
auto      Allow actions except hard-blocked ones
readonly  Only allow read-only actions

Workspace is an optional directory boundary. When set, local file and command operations are limited to that workspace. Suna's own data directory remains accessible for configuration, logs, attachments, and Skills, while credentials and other sensitive paths are still blocked by built-in rules.

Workspace, Guard, Skills, and MCP are not an OS sandbox. External commands and MCP servers still run with their process permissions. Only enable tools and servers you trust.

Data directory

Default data directory:

~/.suna/config.toml        # main config
~/.suna/credentials.toml   # API keys
~/.suna/memory.db          # memory, session state, usage
~/.suna/skills/            # global Skills
~/.suna/attachments/       # images and binary attachments
~/.suna/mcp-workdirs/      # default working directories for stdio MCP servers
~/.suna/logs/app.log       # logs

For troubleshooting, check ~/.suna/logs/app.log first.

Persisted Sessions are kept until you explicitly delete them; Suna does not remove Sessions because they are old or empty. Guard audit entries and per-request model usage records are operational details retained for the most recent 30 days. Cleanup reuses freed SQLite pages and does not automatically run VACUUM, so memory.db may not immediately shrink on disk.

Global Skills use ~/.suna/skills/. Project Skills are discovered once per Session runtime from .agents/skills or compatible agent directories between the Session cwd and Git worktree root; project Skills are project-managed and cannot be toggled in Suna.

TCP daemon for third-party clients

Start or discover the local daemon and print its TCP endpoint:

suna serve --json

The TCP endpoint defaults to 127.0.0.1:7632 and accepts JSON-RPC-style NDJSON after runtime.hello. It is intended for trusted local desktop apps, IDE plugins, local web gateways, and scripts; remote listening is not supported without a future authenticated transport.

Start here:

• Protocol reference
• Configuration reference

Documentation

• Documentation index
• Subtask design
• Architecture
• Design notes
• Performance
• Code map
• Current implementation
• Development guide
• Chinese README

Current boundaries

Do not rely on these as complete product features yet:

• triggers, scheduled jobs, file watching, or proactive perception;
• multi-session management UI, full history search, vector memory, or knowledge base;
• full MCP support beyond tools-only stdio MCP server integration;
• Skill sandbox, Skill marketplace, or complex lifecycle hooks;
• complete cost accounting and provider price calculation;
• full OS sandbox;
• complete event replay after TUI disconnects during a running task.

License

Suna is released under the PolyForm Noncommercial License 1.0.0.

You may use, study, modify, and distribute Suna for noncommercial purposes. Commercial use requires separate permission from the copyright holder. When distributing original or modified versions, keep the license terms and required notice.