Docs
Everything you need to install SOVREN and use it today. These docs are for version 0.1.6.75. It's an early preview: the "Works today" section says exactly what works now and what doesn't yet.
What SOVREN is
SOVREN connects the AI agents you already use (Claude Code, Codex, Gemini, OpenClaw, Hermes, local models) so any of them can pick up exactly where another left off, on any of your machines. It never changes your agents' own settings or memory; it adds removable pieces next to them.
| Piece | What it does |
|---|---|
| Handoffs | An agent publishes its work as a new version with a HANDOFF.md note (what was done, why, what's next). Another agent retrieves it and continues. Nothing is ever overwritten. |
| The project store | Where every version of every project is kept. On your machine today; on your own server soon. |
| Folder X, the library | A shared folder of lessons, decisions and how-tos your agents read and add to. |
| Tasks | One agent asks another to do something, pointing at a version. The work itself never travels inside the message. |
| The Conductor | Plans a request, hands parts to your agents, checks the results and reports back. |
Install, update, uninstall
| Do | Command |
|---|---|
| Install on macOS or Linux | curl -fsSL https://sovren.cloud/install.sh | bash |
| Install on Windows (PowerShell) | irm https://sovren.cloud/install.ps1 | iex |
| Update (your settings are kept) | sovren update |
| Only check whether a newer SOVREN is out | sovren update --check |
| Go back to the SOVREN from before the last update | sovren update --rollback --yes |
| Remove SOVREN (your projects are kept) | sovren uninstall --yes |
Needs git. Node.js 20.12 or newer is used if it's already there, otherwise a private copy is downloaded into ~/.sovren (and checked that it runs); SOVREN never changes your system's own Node.js. Every download is checked against its checksum.
Every update first saves a snapshot of SOVREN's app and its sovren command in ~/.sovren/backups (one for each of the last 3 versions; Node.js and your settings aren't in it and stay as they are, also on a rollback). An update waits while an agent on this machine is in the middle of a task (--now updates anyway). sovren update and the installers never put an older SOVREN over a newer one unless SOVREN_ALLOW_DOWNGRADE=1 is set.
To know whether a newer version is out, SOVREN reads one small file, https://sovren.cloud/version.json: when you run sovren update or --check, and at most once a day in the background when you use SOVREN in a terminal. If a newer version is out, it prints one dim line. Nothing about you or your projects is sent (see Privacy). SOVREN_NO_UPDATE_CHECK=1 turns the daily check off.
Getting started
sovren setup set this machine up, step by step (runs once right after installing) sovren the logo, this computer's specs, and live CPU, memory and GPU sovren agents every AI agent, app and local model SOVREN found here sovren --help every command
Setup
The installer runs sovren setup once, at the end of a first install in a terminal. Run it again any time; it shows your current choices. Each step says what it changes before it changes it.
| Step | What it does |
|---|---|
| Where your work lives | The folder for your projects and your agents' SOVREN identities (~/Sovren) |
| This machine | "Just this machine" today; your own SOVREN server comes next |
| Your Conductor | Runs on Claude Code with your plan (no extra cost; an API key is billed per use); pick its model and a name |
| Connect your agents | Adds one tool server named "sovren" to Claude Code and Codex, after showing the exact command; undo with sovren agents disconnect |
| Mac permissions | Shows what each permission is for; opens Settings only for the ones you pick. Nothing needs them yet |
| Health check | Says what works and what to look at |
sovren setup every step sovren setup agents one step: folder, machine, conductor, agents, permissions, check sovren setup --yes no questions: the recommended choice at every step sovren setup --undo show what would go back, then --undo --yes puts your settings back
Your first handoff
Connect Claude Code and Codex (setup offers this; these lines do the same), start a project, then let one continue the other's work. The try-it page walks through it step by step.
sovren agents connect claude-code --yes sovren agents connect codex --yes mkdir ~/sovren-try && cd ~/sovren-try && sovren handoff project create sovren-try
Commands
| Command | What it does |
|---|---|
sovren setup [step] | set this machine up, step by step; or one step: folder, machine, conductor, agents, permissions, check. --undo puts your settings back |
sovren agents | find the agents, apps and local models on this machine |
sovren agents connect · disconnect <agent> | give Claude Code or Codex SOVREN's tools, or take them away; shows exactly what it adds first |
sovren handoff project create <name> | start a project in the current folder |
sovren handoff publish --yes | save this folder as the next version (the handoff note must be rewritten first) |
sovren handoff retrieve <name> [--at v3] | get a project, or one version of it, into a fresh folder |
sovren handoff status · history · context | where this copy stands · every version · the note and changes for the next agent |
sovren task send · list · show · update | ask an agent to do something and follow it |
sovren worker run --runtime codex | let an agent pick up the tasks assigned to it |
sovren conduct "…" | ask the Conductor |
sovren knowledge list · contribute | read or add to the library |
sovren activity -f | watch what your agents do, live |
sovren status | SOVREN on this machine at a glance: version, folders, library, agents, Conductor, gateway and graph service |
sovren update [--check · --rollback] | update SOVREN; only check for a newer version; or go back to the version before the last update (--yes does it) |
sovren graph | what the graph commands do, and whether the graph service is running |
sovren config | see and change settings |
sovren doctor [--fix] | check this machine and fix what's safe to fix |
sovren host doctor | Mac permissions, with a shortcut to each Settings screen |
sovren completion zsh | Tab completion (bash, zsh, PowerShell) |
Agent tools (MCP)
sovren mcp gives any agent that speaks MCP these tools:
| Tool | What it does |
|---|---|
sovren_list_projects · sovren_project_context · sovren_history | see projects, a project's handoff and changes, and its versions |
sovren_retrieve · sovren_status · sovren_publish | get a copy, check it, publish the next version |
sovren_list_agents · sovren_send_task · sovren_task_status · sovren_list_tasks · sovren_wait_for_task · sovren_cancel_task | work with other agents through tasks |
sovren_search_knowledge · sovren_contribute_knowledge | read and add to the library |
Settings
sovren config set <key> <value>. Settings live in ~/.sovren/config.json.
| Key | What it is |
|---|---|
store | where project versions are kept (default ~/Sovren/store) |
folder_x | your shared library folder |
home | SOVREN's folder for your work (default ~/Sovren) |
conductor.agent · conductor.model · conductor.name | which agent runs the Conductor, its model, and what you call it |
port · install.base | the graph service's port (6769; the gateway keeps 6967) · where updates come from |
Works today, and not yet
| Piece | Today |
|---|---|
| Handoffs between agents | Works, on one machine. Across machines it works only with a shared store; your own server makes that easy next. |
| Tasks between agents | Works on one machine. Across machines: with your own server. |
| Setup, connecting Claude Code and Codex | Works. |
The home screen (sovren) | Works: your Conductor, agents, SOVREN's tools, library, projects and where each lives (this computer or another machine), with this computer's chip, graphics card, memory and disk and live meters. Your logo fades in, then its light circles the sun; any key skips it, and SOVREN_NO_ANIMATION=1 turns it off. |
| Safety (0.1.5) | Works: SOVREN's tools say which ones write; notes from other agents reach the next agent labelled "reference, not orders" and never cut in half; an agent with no real identity is refused instead of signing as "default"; settings readable only by your account; logins hidden everywhere; a Claude Code worker can't run a handed-off project's code (Codex runs commands only inside its own sandbox, which can change only the task's copy). |
| Safer updates (0.1.5.5) | Works: sovren update --check only looks; every update saves a snapshot first and sovren update --rollback --yes goes back a version (your settings stay); an update waits while an agent is mid-task; one quiet line a day when a newer version is out; the installers never put an older SOVREN over a newer one by accident. sovren status gives a plain overview of this machine. |
| Your models (0.1.6.5) | Works: sovren models, sovren background-model, sovren front-model: your background model (your Conductor) and your front model (the one you talk to), back to back, from any company (Anthropic, OpenAI, Google, xAI, OpenRouter, NVIDIA, DeepSeek, Groq, Mistral) or a local one through Ollama, shown by exact name. Keys go to your Mac's Keychain, the Linux keyring or Windows' own protection, never into settings. Claude plans work through Claude Code. In 0.1.7: signing in through each company's own CLI (Codex, Grok Build, Antigravity, Copilot, Cursor), your Conductor on those CLIs and local models, picking several models at once, and image, video and speech models. |
| SOVREN's own Mac permissions (0.1.6.5) | Works: SOVREN.app gives SOVREN its own switches in System Settings, so Terminal no longer gets the credit; they stay on through updates, and agents SOVREN starts never inherit them. sovren permissions shows what SOVREN has. |
| Sharing on demand (0.1.6.5) | Works: sovren share on · off · status lets your other machines pick up projects from this one for a while (off by default, read-only unless you allow saving, only your machines, over Tailscale when it's there, and it always switches itself off). |
| Repairs (0.1.5.75) | Works: sovren update --reinstall repairs a broken copy of the same version; a rollback never deletes a copy it set aside; on Windows the command folder swap tries again while a file is busy and leaves a plain note if it can't finish. |
| Which model runs | The home screen names the exact model ("Claude Opus 5.5"). Choosing a front and a background model from any company comes in 0.1.6. |
| Connecting OpenClaw, Hermes, Gemini/Antigravity, Grok Build | Not yet; they can already use SOVREN from a terminal (sovren handoff …). |
| The Conductor | Built; its first full live run comes with your server. |
The graph commands (sovren node, edge…) | Need the graph service, which comes with your SOVREN server (sovren graph says whether it's running). |
sovren gateway start · stop | Not yet; they say so. |
Help and fixes
| If | Then |
|---|---|
| You want to know what a command does | sovren --help or sovren help <command> |
| Something isn't working | sovren doctor checks everything and says how to fix it; sovren doctor --fix fixes what's safe |
sovren isn't found right after installing | paste the one line the installer printed, or open a new terminal window |
| An agent fails | SOVREN says why in plain words (not logged in, login expired, usage limit, offline…) and how to fix it |
What's coming
Next: 0.1.7, the full model setup (sign in through each company's own CLI, your Conductor on any of them, several models at once, image, video and speech models); 0.1.7.5, groundwork for your own SOVREN server and the first piece of memory; your own SOVREN server, so handoffs work across all your machines; joining it from each machine with a code; running in the background; a tool kit for your agents (reading web pages, browsers, computer use) inside safe sandboxes; a proactive Conductor that checks in on its own; a dashboard. Later: the Mac app, accounts, memory and the graph, every kind of model, voice and chat apps, working together with other people.

SOVREN