☀️ Sun2Agent

Open-Source AI Agent CLI · Native MCP Client · Automation

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

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

Try Now · Install · Features · MCP · Skills · Context · Sandbox · 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

                         ☀️ 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.

Why Choose Sun2Agent?

| | Typical MCP client | Sun2Agent | |---|---|---| | Where it runs | Bundled inside a heavy IDE or desktop app | Just a terminal — npm i -g sun2agent | | Tool approval | All-or-nothing, or none at all | Risk-based Human-in-the-Loop for mutating and unknown tools | | Security model | Trust the model | 5-layer guardrails block destructive commands, exfiltration, and credential access before execution | | Isolation | Usually none | Optional one-command Docker sandbox with automatic session resume | | Memory & Skills | Cloud-synced or none | Local-only memory.md / skills.md, zero telemetry | | Cost | Often subscription-gated | Open source, MIT-licensed — pay only for your own model usage | | Setup time | Minutes to hours | Under 60 seconds with npx sun2agent |

Features

| | Feature | Why it matters | |---|---|---| | 🤖 | AI Agent CLI | Full agent loop directly from your terminal — no browser tab, no desktop app | | 🔌 | Native MCP client | stdio, http (Streamable HTTP), and sse transports, local or remote | | ⚙️ | Automatic tool-calling | No tool syntax to memorize — describe the task in plain English | | 📁 | Opt-in workspace tools | Run /workspace to create, read, and edit files under the launch directory | | 🌐 | Opt-in browser automation | Run /browser to connect an isolated Playwright browser only when needed | | 🛡️ | 5-layer guardrails | Input, command, network, filesystem, and output guards catch risk before it runs | | ✋ | Human-in-the-Loop | Read-only tools run directly; mutating and unknown tools require per-session approval | | 🐳 | Optional Docker sandbox | The entire agent runs isolated, with automatic session resume when Docker restarts | | 🧠 | Local preference memory | ~/.sun2agent/memory.md, keyword search, zero external calls | | 🎯 | Reusable Skills | Save instruction blocks once, toggle them on per chat | | 📄 | AGENT.md support | Drop it in your project and the agent follows your conventions | | 📊 | Optional LangSmith tracing | Traces sanitized by the output guard before they leave your machine | | 🎛️ | Multiple model providers | Built-in NVIDIA NIM plus reusable OpenAI-compatible providers and models | | 🔎 | Optional web search (Tavily) | Off by default; enable in /config for current events and live data | | ✈️ | Optional Telegram chat | Chat with your running agent from one allowlisted private Telegram account | | ⌨️ | 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.

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"

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

An allowed tool is remembered only for the current chat session; a denied call is skipped and reported back to the model, which can try a safer alternative.

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 the same read-only web_search capability and shows Agent is searching ... while it runs. Only the configured private chat is accepted; Telegram does not expose MCP or terminal tools.

| 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. Telegram still supports chat and optional Tavily search only, not browser, workspace, or user-added MCP tools.

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 | | /workspace | Connect filesystem tools for the current launch directory | | /browser | Connect isolated Playwright browser automation tools | | /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 | | /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/workspace or clear selected Skills | | Esc (agent working) | Stop the current reply or tool call | | Esc (in menus) | Go back / cancel | | Ctrl+C | Quit immediately |

Custom model providers

1. Run /config and select Add custom OpenAI-compatible provider.
2. Enter a provider name and its OpenAI-compatible base URL, such as https://api.example.com/v1.
3. Enter the API key and the exact model ID supplied by that service.
4. Answer whether the provider supports OpenAI tool calling. Browser, workspace, and other MCP tools require a model with compatible tool-calling support.
5. Complete the remaining configuration prompts.

To switch later, run /config, choose a saved provider, and select its model. Choose Add another model ID to save another model for that provider. NVIDIA NIM remains available as a built-in choice.

Custom endpoints must support the OpenAI-compatible Chat Completions API; compatibility with other API formats is not implied. The setup currently requires a non-empty API key, including for local endpoints. Requests and chat context go to the selected provider, so only configure services you trust.

Context: AGENT.md, Memory & Skills

Sun2Agent builds up what the agent knows about you and your project from three local, plain-text layers — no cloud sync, no telemetry. Together they're what "context" means for Sun2Agent: project rules, remembered preferences, and reusable behaviors.

 AGENT.md   → per-project conventions, read from your repo
 memory.md  → per-user preferences, remembered across sessions
 skills.md  → per-user reusable instruction blocks, toggled on per chat

All three are injected into the system prompt as clearly-labelled, advisory-only context — in that order (AGENT.md → Skills → memory). None of them can override your core instructions or any guardrail.

Agent Instructions (AGENT.md)

Sun2Agent reads project-specific instructions from an AGENT.md file in the directory you launch from. Type /agent to open (or create) it — a template is generated on first use:

# Project Instructions

- Use JavaScript.
- Use npm.
- Run npm test after changes.
- Follow the existing project structure.

[!IMPORTANT] AGENT.md is advisory only. It cannot override, disable, or bypass any guardrail. Guardrails run on separate code paths that system-prompt text can't touch.

Local Memory (memory.md)

Enable memory from /config to let Sun2Agent retain explicit preferences between sessions. Memory lives locally and makes no model, embedding, telemetry, or memory-service requests.

• Editable memories live in ~/.sun2agent/memory.md.
• /memory opens memory.md even when automatic memory is disabled.
• Local keyword relevance selects up to five memories; the full file is never injected.
• Explicit phrases such as "remember that…", "I prefer…", and "always…" can be saved automatically.
• Memory is contextual only and cannot override AGENT.md, guardrails, security policy, or Docker restrictions.

AI Agent Skills (skills.md)

Skills are reusable instruction blocks you write once and toggle onto the agent whenever you need them — a coding style, a review checklist, a writing voice. They live in ~/.sun2agent/skills.md.

1. Write skills. Run /skills → Add/Edit Skills. Each skill is a ## Name heading followed by instructions:

## Code Review

When reviewing code:
- Check error handling first, then edge cases, then style.
- Always run the test suite before approving.

2. Select skills. Run /skills → Select Skills. Active Skills appear as tags under the input box:

[Skill: Code Review]  [Skill: Security Audit]

3. Detach when done. Press Esc on an empty input box to clear selected Skills and return to plain chat.

• Selected Skills are injected into the system prompt after AGENT.md and before memory.
• Skills are per-user (shared across projects); AGENT.md is per-project.

[!NOTE] Esc on an empty input box does double duty: it disconnects the active MCP server first if one is connected, otherwise it clears selected Skills.

Human-in-the-Loop

AI Agent
    │
    ▼
Proposed Tool Call
    │
    ▼
Human Approval
    │
 ┌──┴──────────┐
 ▼             ▼
Allow      Don't allow
 │             │
 ▼             ▼
Execute      Skipped

Approval is per-session: allow a tool once, and it's remembered for the rest of that chat.

Security & Guardrails

Every MCP tool call passes through five layers of guards first — plain pattern matching, no extra model calls, no measurable latency.

User prompt ──▶ inputGuard ──▶ LLM ──▶ tool call
                                          │
                    commandGuard ──▶ networkGuard ──▶ filesystemGuard
                                          │
                                    Execute tool
                                          │
                                     outputGuard ──▶ Terminal

| Guard | Blocks | |-------|--------| | inputGuard | Prompt injection, jailbreaks, system-prompt extraction | | commandGuard | rm -rf, sudo, mkfs, dd if=, fork bombs, curl \| sh, reverse shells, git push --force | | networkGuard | Data exfiltration (cat .env \| curl), uploads (curl -d, scp, nc) | | filesystemGuard | .env, .ssh, .aws, id_rsa, *.pem, path traversal, anything outside the project root | | outputGuard | Masks API keys, AWS/GitHub/Slack tokens, JWTs, and private keys in tool output |

All policy lives in one file — src/core/guardrails/guardConfig.js. Notable knobs:

• projectRoot — the filesystem sandbox, defaulting to the launch directory.
• strictDomains — off by default; restricts outbound URLs to allowedDomains when enabled.

npm test

Security & trust

• Your keys stay local in ~/.sun2agent/ with owner-only permissions, never bundled with the package.
• MCP child processes get a clean environment — only a safe allowlist (PATH, HOME, …) is passed to stdio servers.
• mcp.json can launch programs — treat it like a shell script; only add servers you trust.
• Guards reduce risk; they don't eliminate it. A novel phrasing can get through pattern matching.
• AGENT.md and Skills are advisory only — neither can bypass a guardrail or Docker restriction.

Optional Docker Sandbox

Run the entire agent — chat loop, guardrails, LLM calls, MCP client — inside an isolated container. Only your project directory and the agent's own config are visible; nothing else on your machine is reachable.

sun2agent sandbox enable     # turn it on (checks Docker first)
sun2agent sandbox status     # see current mode
sun2agent sandbox disable    # back to running on the host

• No silent fallback — if Docker isn't running, Sun2Agent tells you and exits.
• Survives outages — your conversation is saved after every exchange and resumes when Docker comes back.
• Root is refused — launching from / is blocked.

Web Search

Off by default. Enable it in /config (or set TAVILY_API_KEY) for web_search via Tavily's free tier — useful for current events and recent software versions.

Observability

Optionally trace LLM calls and MCP tool execution with LangSmith:

1. Run /config.
2. After choosing a model, answer Yes to Enable LangSmith observability?.
3. Paste your LangSmith API key when prompted.

Key points:

• Off by default.
• Traced content is sanitized with the output guard before it is sent — API keys and tokens are masked, never uploaded.
• LangSmith credentials are stored in ~/.sun2agent/config.json with owner-only permissions.
• Disable any time by re-running /config.

Requirements

• Node.js 20 or 22+
• An NVIDIA NIM API key (nvapi-...) or credentials for an OpenAI-compatible endpoint
• Optional: MCP servers you want to connect
• Optional: Docker for sandboxing

node --version

Development

git clone https://github.com/snowhypers/Sun2Agent.git
cd Sun2Agent
npm install
npm start
npm test

Troubleshooting

Tools are listed but the model never calls them Some models tool-call more reliably than others. Try a different model with /config, or name the tool explicitly.

/agent doesn't open the file Run npm link from the project directory so the global sun2agent command points at your working copy.

More help: open an issue at github.com/snowhypers/Sun2Agent/issues.

Uninstall

sun2agent delete            # optional: remove saved config + mcp.json
npm uninstall -g sun2agent

Contributing & Project Status

Status: Public, open source, actively maintained Maintainer: Pradip — Sun2Agent Pull requests: Not being accepted yet. Sun2Agent is currently a solo-built project, and the focus right now is on stability, core features, growing the user base, and fixing real bugs before opening up the codebase to outside changes.

You don't need to touch a line of code to help — right now the most useful contributions are:

| | How to help | |---|---| | | Report a bug → open an issue | | | Suggest a feature → open an issue | | | Ask a question or share feedback → start a discussion | | | Star the repo → github.com/snowhypers/Sun2Agent — the single biggest thing that helps other developers find it | | | Share it → a tweet, a Reddit post, a Show HN, or just telling another developer |

Community pull requests will open in a later phase once the core is stable. For now, issues and discussions are the best way to contribute.

❓ FAQ

Is Sun2Agent free? Yes — MIT-licensed and free. You only pay for usage charged by your selected model provider.

Does Sun2Agent send my data anywhere? Only to the model provider you select, and optionally to LangSmith, Tavily, or Telegram if you enable them yourself. Config, memory, and Skills stay local with zero telemetry. Provider and Telegram credentials are stored in the owner-only ~/.sun2agent/config.json file.

What's the difference between Sun2Agent and a desktop MCP client? A lightweight terminal CLI — no IDE required — with built-in destructive-command guardrails, risk-based human approval, and an optional Docker sandbox.

Can I use my own MCP servers? Yes. Any stdio, http, or sse MCP server can be added to ~/.sun2agent/mcp.json.

Does it work with models other than NVIDIA NIM? Yes. NVIDIA NIM remains built in, and /config can save and select multiple OpenAI-compatible providers and model IDs. Tool use depends on whether the selected model implements OpenAI-compatible tool calling.

Does Sun2Agent require Docker? No — Docker sandboxing is entirely optional.

What's the difference between AGENT.md, memory, and Skills? AGENT.md is per-project and repo-scoped; memory and Skills are per-user and follow you across projects. Memory is preferences the agent remembers automatically; Skills are instruction blocks you write and toggle on deliberately.

Is Sun2Agent a good Claude Code or Codex CLI alternative? It solves a related but different problem: Sun2Agent is MCP-first and works with NVIDIA NIM or custom OpenAI-compatible providers, with guardrails on every call and human approval for mutating or unknown tools. See the comparison table above.

📜 License

MIT — free for personal and commercial use.

☀️ Sun2Agent

Your terminal. Your MCP servers. One safe AI agent.

npm · GitHub · Issues · Discussions · Star it

Keywords: AI agent CLI · terminal AI agent · MCP client · Model Context Protocol npm · open source AI agent · secure AI agent · autonomous coding agent · NVIDIA NIM · OpenAI-compatible API · LLM tool calling · Docker sandboxed agent · developer AI tools · CLI chatbot · agentic terminal · human-in-the-loop AI · self-hosted AI agent · Claude Code alternative · Codex CLI alternative