# Sofia

> Autonomous local AI assistant in Go — 40+ tools, 20+ LLM providers, multi-agent orchestration, self-improving

- **Type:** MCP server
- **Install:** `agentstack add mcp-grasberg-sofia`
- **Verified:** Pending review
- **Seller:** [grasberg](https://agentstack.voostack.com/s/grasberg)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [grasberg](https://github.com/grasberg)
- **Source:** https://github.com/grasberg/sofia
- **Website:** https://github.com/grasberg/sofia

## Install

```sh
agentstack add mcp-grasberg-sofia
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🤖 Sofia

### Your Local-First, Autonomous AI Colleague

[](https://github.com/grasberg/sofia/stargazers)
[](https://github.com/grasberg/sofia/network/members)
[](https://github.com/grasberg/sofia/blob/main/LICENSE)
[](https://go.dev/)
[](https://github.com/grasberg/sofia/commits/main)
[](CONTRIBUTING.md)

**A self-improving AI orchestrator that runs on your own machine.**
Single Go binary. 60+ tools. 188 models across 19 LLM providers. Multi-agent coordination.
Persistent memory with a knowledge graph. Browser automation. Computer control.
**And it gets better at its job over time.**

[🚀 Quick Start](#-quick-start) · [✨ Features](#-key-features) · [🏗️ Architecture](#-architecture) · [🤝 Contributing](CONTRIBUTING.md)

---

## Why Sofia?

Most AI assistants are cloud-locked chatbots that wait for you to type something. **Sofia is different.**

- 🏠 **Local-first** — Your config, memory, and history live on your machine in SQLite under `~/.sofia`. (LLM inference still calls a provider's API unless you run a local model with Ollama.)
- ⚡ **Single binary** — Written in Go. No Python, no Node.js, no Docker required. Just `make build`.
- 🧠 **Self-improving** — An opt-in evolution engine analyzes past performance and tunes the agent roster.
- 🤖 **Multi-agent** — Spawn, coordinate, and retire agents dynamically. Agent-to-agent messaging built in.
- 🔐 **Safety built in** — Approval gates on side-effectful tools (on by default, fail-closed). Opt-in prompt-injection and PII guardrails. Model API keys encrypted at rest (AES-256-GCM) when you set `SOFIA_DB_KEY`.
- 🌐 **19 LLM providers** — OpenAI, Anthropic, Gemini, DeepSeek, Grok, Mistral, Groq, OpenRouter, Ollama, and more, with automatic fallback.

---

## 🚀 Quick Start

Install the binary, run the setup wizard, and open the dashboard:

```bash
# 1. Install (downloads the latest release, verifies its checksum, installs to ~/.local/bin)
curl -fsSL https://raw.githubusercontent.com/grasberg/sofia/main/install.sh | sh

# 2. First-run wizard: writes config, seeds the workspace, and configures a model
sofia onboard

# 3. Start the gateway (channels + web UI)
sofia gateway
# → Web UI at http://127.0.0.1:18795
```

`sofia onboard` detects provider API keys from your environment (`ANTHROPIC_API_KEY`,
`OPENAI_API_KEY`, `GEMINI_API_KEY`, and others), lets you pick a provider, validates the key
with a live one-token request, and saves it. If you skip it, add a model any time from the
Web UI **Models** page.

> **Note:** the `install.sh` one-liner downloads a published GitHub release. Until the first
> release is tagged, build from source (below) — that path works today.

Build from source

```bash
git clone https://github.com/grasberg/sofia.git
cd sofia
make deps && make build     # produces ./build/sofia
./build/sofia onboard
./build/sofia gateway
```

**Prerequisites:** Go 1.25+ ([download](https://go.dev/dl/)).
Always build with `make build` — a bare `go build` skips `go generate` and embeds a stale workspace.

See the [Installation Guide](docs/installation.md) for platform notes, upgrading, and running as a service.

---

## ✨ Key Features

### 🛠️ Autonomous Tool Use
Read and edit files, run shell commands, search and browse the web, query databases,
manage Google services (Gmail/Calendar/Drive via `gog`) and GitHub (via `gh`) — with
approval gates on anything that has side effects.

### 🧠 Advanced Memory
A tiered memory system — short-term session history, a long-term semantic knowledge graph,
episodic notes and reflections, and named checkpoints — persisted in local SQLite with
automatic summarization and consolidation.

### 🤖 Multi-Agent Orchestration
Delegate tasks to parallel agents chosen by semantic matching and reputation scores.
Agent-to-agent mailbox messaging with broadcast, and conflict resolution when parallel
agents disagree.

### 🌐 19 LLM Providers, 188 Models
OpenAI, Anthropic, Gemini, DeepSeek, Grok/xAI, Mistral, Groq, OpenRouter, Moonshot, Qwen,
MiniMax, GitHub Copilot, local Ollama, and more — behind one interface with fallback chains
and per-provider cooldown tracking.

### 📚 Skill System with Self-Learning
120+ built-in skills with expert personas, loaded from markdown `SKILL.md` files. Agents can
discover, install, author, and refine skills at runtime — including pulling from the ClawHub
community registry (experimental; the client and a reference server exist, but the public
marketplace is not yet a stable service).

### 🔄 Evolution & Self-Improvement *(opt-in)*
A 5-phase `EvolutionEngine` (observe → diagnose → plan → act → verify) that reviews past
performance and creates, retires, or tunes agents. Disabled by default; enable it in config
or trigger a single cycle with `/evolve`.

### 🖥️ Computer Use
Autonomous desktop control via screenshots and a vision model — mouse and keyboard on macOS
and Linux.

### 🌍 Browser Automation
Playwright-based web browsing: navigate, click, fill forms, screenshot, extract text. The
~250 MB browser runtime downloads automatically the first time a browser tool is used, not
at startup.

### 🛡️ Guardrails & Security
Approval gates that fail closed (on by default), input validation, budget limits, and a
circuit breaker for repeatedly failing tools. Prompt-injection defense and PII
detection/redaction are available as opt-in guardrails (off by default; enable in config).

📋 More Features

- **MCP** — Act as a Model Context Protocol server (`sofia mcp-server`), and connect to external MCP servers as tools.
- **Gateway Mode** — Telegram, Discord, Email, Web, and CLI channels through one service.
- **Autonomy & Proactivity** *(on by default)* — Long-term goals, context triggers, a heartbeat, and background research delivered to your last active channel.
- **Cron Scheduling** — One-time (`at`), interval (`every`), and cron-expression jobs from chat, CLI, or the dashboard.
- **Workflows** — Deterministic multi-step flows with approval gating (e.g. email support-reply, GitHub issue fixing).
- **Voice** — Speech-to-text for Discord/Telegram voice notes; text-to-speech via ElevenLabs or the OS engine.
- **Remote Access** — Expose the dashboard over your tailnet (or publicly) via Tailscale.
- **Modern Web UI** — Real-time updates, streaming chat, file uploads, and settings for every subsystem.

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Channels (Input)                      │
│   Telegram  ·  Discord  ·  Email  ·  Web UI  ·  CLI      │
└──────────────────────────┬──────────────────────────────┘
                           │
                    ┌──────▼──────┐
                    │   Gateway    │  ← HTTP/WebSocket + health endpoints
                    └──────┬──────┘
                           │
              ┌────────────┼────────────────┐
              │         Orchestrator          │
              │  ┌─────────┴──────────┐      │
              │  │  Evolution Engine   │      │  (opt-in)
              │  │  (Self-Improvement) │      │
              │  └────────────────────┘      │
              │                               │
              │  ┌──────────┐  ┌──────────┐  │
              │  │  Agent 1  │  │  Agent 2  │  │  (A2A messaging)
              │  └─────┬────┘  └─────┬────┘  │
              └────────┼─────────────┼────────┘
                       │             │
              ┌────────┴─────────────┴────────┐
              │         Tool Layer             │
              │  File · Shell · Web · Browser  │
              │  GitHub · Google · Bitcoin     │
              │  Cron · Memory · Plan · MCP    │
              └───────────────┬────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   LLM Providers    │
                    │  19 with fallback  │
                    └───────────────────┘
```

For a full, source-grounded walkthrough of every subsystem, see [docs/features.md](docs/features.md).

---

## ⚔️ Comparison

| | **Sofia** | **AutoGPT** | **CrewAI** | **LangChain** | **OpenDevin** |
|---|:---:|:---:|:---:|:---:|:---:|
| **Local-first state** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Single binary** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **60+ built-in tools** | ✅ | Limited | Via plugins | Via plugins | Limited |
| **Knowledge graph** | ✅ | Basic | ❌ | ❌ | ❌ |
| **Self-improving** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Multi-agent orchestration** | ✅ | Basic | ✅ | Basic | ❌ |
| **Browser automation** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Computer use** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Security guardrails** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Language** | Go | Python | Python | Python | Python |

"Local-first state" means your config, memory, and history stay on your machine.
LLM inference is served by whichever provider you configure (cloud, unless you run Ollama locally).

---

## 📂 Where Sofia stores things

```
~/.sofia/
├── config.json          # channels, gateway, web UI, agents, tools, guardrails
├── memory.db            # model catalog + API keys, memory, goals, sessions (SQLite)
├── audit.db             # structured audit trail of every action
├── workspace/
│   ├── AGENT.md         # base agent instructions
│   ├── IDENTITY.md      # who Sofia is
│   ├── SOUL.md          # personality & behavior rules
│   ├── USER.md          # your preferences
│   ├── skills/          # 120+ skill definitions (name/SKILL.md)
│   └── agents/          # 40 agent templates (flat .md files)
└── logs/                # written when running as a background service
```

Nothing here lives in the repo — runtime state is entirely under `~/.sofia`.

---

## 🗺️ Roadmap

- [ ] **Published release binaries** — first tagged GitHub release + Homebrew tap
- [ ] **Plugin SDK** — third-party tool development kit
- [ ] **Team Mode** — multi-user collaboration
- [ ] **Cloud Sync** — optional encrypted backup

---

## 🤝 Contributing

We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, conventions, and the PR process.

Whether you are fixing a bug, adding a feature, improving docs, or sharing a skill — every contribution matters.

## 🛡️ Security

- **Secrets at rest** — Set `SOFIA_DB_KEY` (16+ chars) and Sofia encrypts model API keys in
  the local SQLite database with AES-256-GCM (key derived via PBKDF2-SHA256, per-install salt).
  Without the key, secrets are stored in plaintext in your local DB — set it to encrypt them.
- **Web UI binds loopback** — The dashboard listens on `127.0.0.1` by default. It has no auth
  unless you set `webui.auth_token`, and it can execute commands via chat — so the gateway
  **refuses to start** on a non-loopback interface unless a token is configured.
- **Approval gates fail closed** — Side-effectful tools require approval unless you opt out per
  session with `/yolo`; a missing approval gate denies rather than allows.

Found a vulnerability? Please see [SECURITY.md](SECURITY.md) for responsible disclosure.

## 📄 License

Sofia is released under the [MIT License](LICENSE).

---

**[⭐ Star us on GitHub](https://github.com/grasberg/sofia)** · **[🐛 Report a Bug](https://github.com/grasberg/sofia/issues)** · **[💬 Join the Discussion](https://github.com/grasberg/sofia/discussions)**

Made with ❤️ by the Sofia community

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [grasberg](https://github.com/grasberg)
- **Source:** [grasberg/sofia](https://github.com/grasberg/sofia)
- **License:** MIT
- **Homepage:** https://github.com/grasberg/sofia

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-grasberg-sofia
- Seller: https://agentstack.voostack.com/s/grasberg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.