Sun2Agent MCP server

☀️ Sun2Agent

Open-Source AI Agent CLI · Native MCP Client · Free Claude Code Alternative

Your model. Your tools. AI automation in your terminal.

Sun2Agent is a free, open-source AI agent harness with MCP server connections, desktop & browser automation, workspace tools, scheduled tasks & reminders, web search, and Telegram chat. OpenAI-compatible models. Apply reusable Skills (skills.md), agent instructions (AGENT.md), custom memory (memory.md), and self-improvement reflection—with 5-layer guardrails, HITL approvals, an optional Docker sandbox and LangSmith tracing with zero built-in telemetry.

Try Now · Install · Features · MCP · Skills · Cloud / VPS · Security · FAQ

⭐ Star Sun2Agent on GitHub — the fastest way to help other developers discover it.

---

What Is Sun2Agent?

Sun2Agent is an open-source AI agent CLI and native MCP client that runs directly in your terminal — no IDE, no desktop app, no subscription.

It's for developers who want an AI agent that does more than chat: one that can call real tools through the Model Context Protocol, follow your project's own conventions via AGENT.md, reuse specialized instructions with Skills, remember your preferences locally, and ask before touching anything sensitive.

As an agent harness, Sun2Agent brings the model, project context, MCP tools, approvals, and execution loop together in one terminal CLI.

Common searches this answers: terminal AI agent · npm MCP client · AI agent CLI open source · secure autonomous coding agent · Model Context Protocol client npm · Claude Code alternative · Codex CLI alternative · self-hosted AI agent · human-in-the-loop AI agent · computer use agent · desktop automation MCP

                         ☀️ Sun2Agent
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
      Context                 Tools                Security
        │                      │                      │
     AGENT.md                 MCP                 Guardrails
      Skills               Web Search                HITL
      Memory                                        Sandbox
        │                      │                      │
        └──────────────────────┼──────────────────────┘
                               │
                          AI Agent Runtime
                           LLM/ReAct Loop
                     (Reason → Act → Observe → Repeat)
                               │
             ┌──────────────────────────────────┐
             │          OBSERVABILITY           │
             │          LangSmith               │
             │       ├── LLM Tracing            │
             │       ├── MCP Tracing            │
             │       └── Error Visibility       │
             └──────────────────────────────────┘

---

Try It Now

npx sun2agent

Or install it globally so it's available in every terminal session:

npm install -g sun2agent
sun2agent

Connect your tools. Select your Skills. Ask naturally.

---

Features

	Feature	Why it matters
🤖	AI Agent CLI	Full ReAct agent loop directly from your terminal — no browser tab, no desktop app
🎛️	Multiple model providers	Built-in NVIDIA NIM plus reusable custom OpenAI-compatible providers and models
⚙️	Automatic tool-calling	No tool syntax to memorize — describe the task in plain English
🔌	Native MCP client	stdio, http (Streamable HTTP), and sse transports, local or remote
📁	Automatic workspace tools	Autonomous file reading, creation, and multi-file editing scoped to your project
🌐	Opt-in browser automation	Run /browser to connect an isolated Playwright browser only when needed
🖥️	Opt-in desktop control	Run /computer to inspect windows, click UI elements, and automate apps
🔎	Optional web search (Tavily)	Off by default; enable in /config for live web data with prompt injection screening
📄	AGENT.md support	Drop it in your project and the agent automatically follows your conventions
🎯	Reusable Skills	Save instruction blocks once (skills.md), toggle them on per chat
🧠	Local preference memory	~/.sun2agent/memory.md, keyword search, zero external calls
🔄	Self-improvement & reflection	Learns operational lessons from errors with user consent; continuously improves prompts locally
🛡️	5-layer guardrails	Input, command, network, filesystem, and output guards catch risk before it runs
✋	Human-in-the-Loop	Read-only tools run directly; routine and high-risk calls require clear user confirmation
🐳	Optional Docker sandbox	The entire agent runs isolated, with automatic session resume when Docker restarts
✈️	Optional Telegram chat	Chat with your running agent remotely from one allowlisted private Telegram account
⏰	Scheduled tasks & reminders	Set up recurring background jobs or one-time reminders with /schedule
✅	Maven test verification	After writing Java tests, run mvn test in the workspace with fresh approval; report unverified work until it passes
📊	Optional LangSmith tracing	Traces sanitized by the output guard before they leave your machine
⌨️	Responsive terminal UI	Input box and footer adapt to terminal width; resizing preserves typed input

Latest codebase updates

• Bring your own model provider: save multiple OpenAI-compatible providers, add model IDs, and switch between them and built-in NVIDIA NIM through /config.
• Responsive input: the input box redraws when the terminal resizes, with connection tags and model information fitted to the available width.
• Telegram search cancellation: /stop cancels an active model response or pending Tavily search. The interrupted turn is removed from Telegram history so the next message can start cleanly.

These updates describe the current source code. The published npm package may lag behind it; use the development instructions to run your local checkout.

---

Why Choose Sun2Agent?

Feature	Proprietary Agents (Claude Code / Cursor)	Typical MCP Client	Sun2Agent
Model Freedom	Locked to single vendor (Anthropic / Claude only)	Depends on IDE	Any Model (NVIDIA NIM, OpenAI, Groq, Ollama, custom endpoints)
Where It Runs	Proprietary binary or heavy desktop IDE	Bundled inside IDE or desktop app	Lightweight Terminal CLI — npx sun2agent
Tool Extensibility	Closed or limited tool ecosystem	Basic MCP support	Native MCP Client (stdio, http, sse) + Desktop & Browser automation
Human-in-the-Loop	All-or-nothing or auto-executes silently	Unvetted execution	Risk-based HITL (Read-only tools run instantly; mutating tools ask)
Security & Safety	Basic host permissions	Trust the model blindly	5-Layer Guardrails (Blocks injections, destructive commands, credential leaks)
Environment Isolation	Host system access	Host system access	Optional 1-Command Docker Sandbox with automatic session resume
Memory & Skills	Cloud-synced or closed prompt files	Basic configuration	Local memory.md, reusable skills.md, repo-scoped AGENT.md

---

Install

Recommended: install globally so sun2agent is available in every terminal session.

npm install -g sun2agent

Then launch it anywhere:

sun2agent

npx sun2agent

Requirements: Node.js 20 or 22+, plus either an NVIDIA NIM API key or an OpenAI-compatible API endpoint.

[!NOTE] Don't run npm install sun2agent (without -g) inside another project — it can trigger unrelated dependency-resolution errors in that project. Use -g, or npx sun2agent, instead.

---

Quick Start

1. sun2agent       Start the agent
2. /config         Select NVIDIA or add an OpenAI-compatible provider and model
3. /mcp            Add and connect an MCP server
4. Ask naturally   "Read AGENT.md and run the tests"

Each normal launch starts a fresh conversation. Use /new to clear the current chat without archiving it, or /continue to resume the current task after an interruption. After a crash, /continue can restore the current session snapshot; /new deletes that snapshot. Connected tools and the selected model stay as they are. The footer shows estimated tokens retained in the active chat (chat ~3.2k tokens), not provider-reported usage or remaining model capacity. Use /save to preview and optionally keep a short task summary for the current workspace. Approved summaries are stored separately from memory.md in ~/.sun2agent/saved-sessions.json; a relevant summary may be included as context for a later task in the same workspace. /new does not delete approved saved summaries. While a model or tool turn is running, a non-editable input frame and the same footer stay at the bottom of supported terminals; press Esc to stop the turn.

Get a free API key from NVIDIA Build: pick a model, then select Get API Key. Keys begin with nvapi-.

For another OpenAI-compatible service, choose Add custom OpenAI-compatible provider in /config, then enter its provider name, base URL (for example https://api.example.com/v1), API key, and model ID. Providers and model IDs are saved for later selection in the owner-only ~/.sun2agent/config.json file.

MCP Client & Model Context Protocol

                    Sun2Agent
                        │
                 MCP Client Layer
                        │
        ┌───────────────┼────────────────┐
        │               │                │
      stdio            HTTP              SSE
        │               │                │
        ▼               ▼                ▼
   Local Tools     Remote Tools     Remote Tools

Examples of what you can connect: filesystem tools, browser automation (Playwright MCP), databases, internal APIs, or any custom MCP server.

1. Open the config. Run /mcp → Add / Edit MCP. This opens ~/.sun2agent/mcp.json in your editor.

2. Add servers under mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "my-http-server": {
      "type": "http",
      "url": "https://your-server.example.com/mcp",
      "headers": { "AUTHORIZATION": "Bearer YOUR_KEY" }
    },
    "my-sse-server": {
      "type": "sse",
      "url": "https://your-server.example.com/sse"
    }
  }
}

type	Transport	Needs
stdio	Local child process	command, optional args / env
http	Streamable HTTP (alias: remote)	url, optional headers
sse	Server-Sent Events	url, optional headers

Set "enabled": false on any server to skip it without deleting it.

3. Connect. Run /mcp → Connect MCP, then pick a server — or Connect all MCPs to load every server at once. The active server shows as a green @tag under the input box (@allMcps when several are connected).

---

Tool approvals

When a connected MCP tool is needed, Sun2Agent shows the exact proposed call and asks:

Allow this MCP tool call?
Allow — Don't allow
[Enter] Allow    [Esc] Don't allow

Read-only calls need no approval. One approval covers routine changes on the same MCP server for the current prompt, then expires. Deletes, sends, code execution, unknown actions, and other high-risk calls require a fresh decision. A denied call is skipped and reported back to the model.

Telegram (optional)

Run /config and answer Yes to Connect Telegram?. Paste the bot token created with Telegram's @BotFather, then enter your numeric Telegram user/chat ID. Sun2Agent verifies both values and sends a connection message.

Answering No disables the Telegram connection without deleting the saved bot token or chat ID. A later /config can reuse those credentials. They remain in the owner-only ~/.sun2agent/config.json file and are never printed in the terminal.

The CLI must remain running to receive Telegram messages. Beneath each user message, the bot immediately replies with Agent is typing ..., then progressively edits that same reply as text streams in. If Tavily web search is enabled in /config, Telegram can use web_search and shows Agent is searching ... while it runs. To expose a remote MCP tool to the configured private chat, add its exact name to that server's telegramTools array in mcp.json (for example, "telegramTools": ["tavily_search"]). This explicitly trusts the listed tool to run without per-call approval, including any side effects it may have. Only HTTPS remote MCP endpoints are accepted. No MCP tools are exposed to Telegram by default; local MCP, browser, and computer tools remain unavailable.

Telegram command	Action
/start	Show pairing status and help
/new	Clear this Telegram chat's context
/stop	Abort the active model response or pending web search

Stopping a turn removes its incomplete messages from Telegram history; earlier completed conversation remains available.

Scheduled Telegram tasks

With Telegram configured, try Every day at 9 PM, summarize today’s AI news and send it to Telegram or Today at 8 PM, check email. A schedule needs a task, time, and once or daily recurrence; Sun2Agent asks when one is missing or the time conflicts with words like “morning.” Set SUN2AGENT_TIMEZONE to your IANA timezone before creating schedules from Telegram; CLI schedules use the machine timezone. Without that setting, Telegram asks you to configure it instead of silently using the server timezone. /schedule lists jobs in the CLI; select one for details or confirmed deletion. Jobs are stored in ~/.sun2agent/schedules.json and run while the CLI or Telegram service stays open. Scheduled jobs can use web search, but remote MCP tools are withheld. Sun2Agent starts preparing the result about one minute early and retries a failed preparation up to twice. If it is still working at the scheduled time, it sends a Telegram status message, then the result when ready.

VPS / cloud Telegram service

To keep the Telegram bot online when your laptop is off, deploy the Telegram service to a VPS or an always-on cloud worker. This is a separate running instance; the local CLI does not automatically connect to it. Docker is optional—the VPS guide uses systemd directly.

1. Choose a Linux VPS or an always-on worker such as Render Background Worker. Use Node.js 20 or 22+.
2. Set the values from deploy/.env.example in the host's secret settings: provider, model, model API key, Telegram bot token, and Telegram user/chat ID. Add optional integration secrets only when needed.
3. Attach persistent storage and set SUN2AGENT_DATA_DIR to it. Set SUN2AGENT_AGENT_MD to the persistent AGENT.md path. Place mcp.json and any skills.md in the data directory too.
4. Start with npm run start:service. On a VPS, use the provided systemd service; on Render, use npm ci to build and npm run start:service to run.
5. Send a Telegram test message, restart/redeploy, then confirm the bot replies and its memory/schedules persist.

Keep one polling instance per bot token. Telegram only starts configured HTTPS remote MCP servers and only exposes exact tools listed in telegramTools; listing a tool trusts it to run without per-call approval, including possible side effects. Local filesystem, browser, and computer MCPs are not started by the cloud service. Read the deployment guide for complete VPS and Render steps, environment variables, persistent files, security limits, and troubleshooting.

---

Use Cases

Understand an unfamiliar codebase

"Read this repository, explain the architecture, and flag anything risky." With a filesystem MCP server connected, Sun2Agent inspects your project and reports back.

Run project-aware workflows

"Read AGENT.md, follow the project rules, and run the tests." The agent combines your stated conventions with the tools available to it.

Automate browser tasks

"Open this site, take a screenshot, and click the pricing link." Run /browser, then describe the flow in plain English. It uses installed Google Chrome with an isolated temporary profile. Logins, submissions, purchases, uploads, downloads, permission dialogs, and account changes require explicit approval.

Apply a consistent review process Activate a Code Review or Security Audit Skill so every review follows the same checklist, every time.

Execute sensitive actions with a human in the loop Mutating and unknown MCP calls route through guardrails and an explicit approval prompt; read-only calls still pass guardrails but do not interrupt the user.

---

Commands

Command	Action
/help, /?	Show all commands and shortcuts
/config	Select/add model providers and configure optional services and Telegram
/browser	Connect isolated Playwright browser automation tools
/computer	Connect native desktop control on demand; check permissions and choose image support
/computer disconnect	Disconnect desktop control without affecting other plugins
/mcp	Manage MCP servers — add/edit, connect one or all, disconnect
/agent	Open the project's AGENT.md (creates a template on first use)
/memory	Open and edit local ~/.sun2agent/memory.md
/skills	Add/edit skills.md and choose which Skills are active
/schedule	List scheduled Telegram tasks, view details, or delete one
/delete	Delete saved config and data
/exit	Quit

Key	Action
Enter	Send message
Esc (while typing)	Clear the input
Esc (empty box)	Disconnect MCP/browser or clear selected Skills; workspace tools stay available
Esc (agent working)	Stop the current reply or tool call
Esc (in menus)	Go back / cancel
Ctrl+C	Quit immediately

---

Computer control (optional)

Run /computer to start the pinned @zavora-ai/computer-use-mcp package through npx. The first connection may need a download; startup has a 30-second timeout. This controls your real desktop, not an isolated browser. Node.js 20+ and an interactive desktop are required. Docker mode does not expose the host desktop.

On macOS, grant the trusted host Accessibility and Screen Recording permissions; app scripting may additionally request Automation permission. The plugin runs doctor and displays its capability report. A connection alone does not guarantee that every application is controllable.

Choose image support only if your selected model and endpoint support image input. Otherwise the agent uses accessibility tools; screenshots are omitted, not sent as base64 text. In vision mode the latest screenshot can be sent to your model provider; image bytes are excluded from saved chat history and LangSmith traces.

Esc cancels connecting or an active task. Esc on an empty input disconnects /computer first, leaving other plugins connected. At an approval prompt, Esc declines that action. Completed actions cannot be undone by cancellation. Read-only desktop checks, including menu-bar inspection, need no HITL approval. Opening or activating the same app shares one approval for the current prompt; another app or prompt asks again. Clicks, menu selections, typing, scripts and other desktop changes still require fresh approval when HITL is enabled.

To keep model requests smaller, Sun2Agent initially exposes common computer tools and lets the agent find other tools with computer__sun2agent_search_tools when needed. computer__sun2agent_wait_for_window checks for an app window locally, avoiding repeated model calls just to wait and inspect. These helpers do not bypass guardrails or action approvals.

While /computer is connected, transient model HTTP failures retry once, respecting Retry-After up to 30 seconds. Longer cooldowns and invalid requests are returned without retrying. Completed desktop tools are not replayed by this retry.