cyzus/suzent

---

SUMMON A SOVEREIGN GEIST

Your agent should not be an account you rent. It should be a system you own.

SUZENT [soo-zuh-nt] is an open-source, local-first AI agent whose identity, memory, skills, workspace, and runtime remain under your control. Use GPT, Claude, Gemini, DeepSeek, local models, or whatever comes next without resetting the agent that knows you and your work.

Its memory is append-only Markdown on your disk, not rows in someone else’s database. Its tool calls pass through permission modes you define. Its execution is isolated in Docker workspaces you own. It can research, write, code, pursue goals, run scheduled work, connect to your devices, and meet you in Telegram, Slack, Discord, Feishu, or WeChat — always inside boundaries you set.

Models are replaceable. Platforms are temporary. Your agent remains.

---

QUICK START

INSTALL

SUZENT runs on Windows, macOS, and Linux. One command summons it, its Python backend, and the suzent CLI. Git is the only prerequisite; everything else is auto-installed.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/cyzus/suzent/main/scripts/setup.sh | bash

Windows (PowerShell)

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/cyzus/suzent/main/scripts/setup.ps1 | iex"

Mainland China mirror mode

curl -fsSL https://raw.githubusercontent.com/cyzus/suzent/main/scripts/setup.sh | SUZENT_CHINA_MIRROR=1 bash

$env:SUZENT_CHINA_MIRROR="1"; powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/cyzus/suzent/main/scripts/setup.ps1 | iex"

This uses faster mirrors for PyPI, npm, Playwright, Node via nvm, and Rustup. If GitHub itself is slow, set SUZENT_REPO_URL or SUZENT_RELEASE_BASE_URL to a mirror you trust before running the command.

Then bind your keys in ~/suzent/.env and run:

suzent start

THE suzent CLI

suzent --version       # Print the backend version, commit, and UI version
suzent start           # Start the backend and the desktop app (in the background)
suzent serve           # Start the backend only (headless / standalone)
suzent ui              # Start the desktop app against a running backend
suzent logs -f         # Follow the log of a backgrounded process
suzent stop            # Stop the backend server and the dev frontend
suzent restart         # Stop a running backend server, then start Suzent again
suzent doctor          # Check requirements and diagnose a broken install
suzent update          # Update to the latest stable release
suzent check-update    # Report whether a newer release exists
suzent repair          # Recover an interrupted or damaged update

Run suzent --help, or suzent --help, for the full flag set.

UPDATE

suzent update

This installs the latest stable release as one matched set: backend source, locked dependencies, and desktop app. A standalone updater performs the switch outside the active virtual environment, verifies downloaded assets, and rolls back automatically on failure. If an interrupted update needs recovery, run:

suzent repair

Developers working from a source checkout can update main and its frontend dependencies together with plain suzent update; the checkout is detected automatically. The explicit equivalent is:

suzent update --dev

Or re-run the install command above — it detects an existing installation and updates it to the latest stable release.

---

WHAT MAKES AN AGENT SOVEREIGN?

Sovereignty is not merely local execution. It is ownership of the agent’s mind, authority, vessel, and continuity.

THE SOVEREIGN SYSTEM

CHOOSE ITS INTELLIGENCE

Models are engines, not identities. Switch between GPT, Claude, Gemini, DeepSeek, local models, and compatible providers without surrendering the memory, skills, or workspace that make the agent yours.

OWN ITS MEMORY

Conversation facts land in append-only Markdown logs, consolidate into an inspectable notebook, and are indexed for semantic recall—the files stay authoritative, and the LanceDB index can be rebuilt from them at any time. Read, edit, delete, version, and carry that memory yourself.

GOVERN ITS ACTIONS

Autonomy never makes the agent the authority. Tool calls pass through explicit permission modes, scoped rules, path restrictions, and human approval. Docker workspaces isolate execution, while the activity timeline records what ran, what changed, and why it was authorized.

RUN IT ANYWHERE, LET IT WORK

Goals, project tasks, subagents, Cron, and Heartbeat let the agent continue beyond one reply, inside isolated project workspaces and folders you already own—including an Obsidian vault—and across approved companion devices. Interactive turns checkpoint their session workspace before work begins, so retry restores both the conversation and local changes—not just the text.

Extend it further with portable SKILL.md packages and any MCP server you connect.

KEEP ITS CONTINUITY

GitHub Sync carries portable configuration, user skills, and Markdown memory through a private repository while credentials remain device-local. A provider can disappear, a model can change, and a machine can be replaced without taking the agent’s continuity with it.

---

WHERE YOU TALK TO IT

One agent, one memory, reachable from several surfaces. Messaging channels are off by default and access-controlled: a user ID must appear in allowed_users before the agent will answer it.

Each conversation becomes a persistent session, so history, working memory, and extracted facts survive a restart. Uploaded files land in the sandbox at /persistence/uploads/.

---

THE GRIMOIRE

The full index lives in docs/README.md.

---

LORE

SUZENT’s docs and community speak in an occult register. There is a point behind the joke: the vocabulary of summoning and possession fits an agent you actually own far better than the vocabulary of seats, plans, and accounts. If you meet an unfamiliar word in these pages, it is probably here.

---

TECH STACK

• BACKEND: Python 3.12, FastAPI, pydantic-ai, litellm, SQLite.
• FRONTEND: React, TypeScript, Tailwind, Vite, Tauri.
• MEMORY: LanceDB local vector storage.
• SANDBOX: Docker.
• EXTENSIBILITY: MCP, portable SKILL.md packages.

---

CONTRIBUTING

Summoners welcome. See CONTRIBUTING.md for the workflow, and the Development Guide for setup, production builds, and architecture.

---

SECURITY

Found a vulnerability? Please report it privately—see SECURITY.md. Do not open a public issue.

---

LICENSE

APACHE 2.0 © 2026 Yizhou Chi.

Exception for Creative Assets: The creative assets, including the Robot Avatar design, character animations, and project logos, are subject to separate license terms. See TERMS-OF-USE-ASSETS for details.

SUMMON LOCALLY. REMEMBER PRIVATELY. ANSWER TO NO FALSE GOD.