sofia

🤖 Sofia

Your Local-First, Autonomous AI Colleague

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 · ✨ Features · 🏗️ Architecture · 🤝 Contributing

---

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:

# 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.

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). Always build with make build — a bare go build skips go generate and embeds a stale workspace.

See the Installation Guide 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).

• 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.

---

⚔️ 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 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 for responsible disclosure.

📄 License

Sofia is released under the MIT License.

---

⭐ Star us on GitHub · 🐛 Report a Bug · 💬 Join the Discussion

Made with ❤️ by the Sofia community