SOVREN

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 it isInstallGetting startedSetupYour first handoffCommandsAgent toolsSettingsWorks todayHelp and fixesWhat's coming

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.

PieceWhat it does
HandoffsAn 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 storeWhere every version of every project is kept. On your machine today; on your own server soon.
Folder X, the libraryA shared folder of lessons, decisions and how-tos your agents read and add to.
TasksOne agent asks another to do something, pointing at a version. The work itself never travels inside the message.
The ConductorPlans a request, hands parts to your agents, checks the results and reports back.

Install, update, uninstall

DoCommand
Install on macOS or Linuxcurl -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 outsovren update --check
Go back to the SOVREN from before the last updatesovren 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.

StepWhat it does
Where your work livesThe folder for your projects and your agents' SOVREN identities (~/Sovren)
This machine"Just this machine" today; your own SOVREN server comes next
Your ConductorRuns on Claude Code with your plan (no extra cost; an API key is billed per use); pick its model and a name
Connect your agentsAdds one tool server named "sovren" to Claude Code and Codex, after showing the exact command; undo with sovren agents disconnect
Mac permissionsShows what each permission is for; opens Settings only for the ones you pick. Nothing needs them yet
Health checkSays 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

CommandWhat 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 agentsfind 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 --yessave 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 · contextwhere this copy stands · every version · the note and changes for the next agent
sovren task send · list · show · updateask an agent to do something and follow it
sovren worker run --runtime codexlet an agent pick up the tasks assigned to it
sovren conduct "…"ask the Conductor
sovren knowledge list · contributeread or add to the library
sovren activity -fwatch what your agents do, live
sovren statusSOVREN 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 graphwhat the graph commands do, and whether the graph service is running
sovren configsee and change settings
sovren doctor [--fix]check this machine and fix what's safe to fix
sovren host doctorMac permissions, with a shortcut to each Settings screen
sovren completion zshTab completion (bash, zsh, PowerShell)

Agent tools (MCP)

sovren mcp gives any agent that speaks MCP these tools:

ToolWhat it does
sovren_list_projects · sovren_project_context · sovren_historysee projects, a project's handoff and changes, and its versions
sovren_retrieve · sovren_status · sovren_publishget 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_taskwork with other agents through tasks
sovren_search_knowledge · sovren_contribute_knowledgeread and add to the library

Settings

sovren config set <key> <value>. Settings live in ~/.sovren/config.json.

KeyWhat it is
storewhere project versions are kept (default ~/Sovren/store)
folder_xyour shared library folder
homeSOVREN's folder for your work (default ~/Sovren)
conductor.agent · conductor.model · conductor.namewhich agent runs the Conductor, its model, and what you call it
port · install.basethe graph service's port (6769; the gateway keeps 6967) · where updates come from

Works today, and not yet

PieceToday
Handoffs between agentsWorks, on one machine. Across machines it works only with a shared store; your own server makes that easy next.
Tasks between agentsWorks on one machine. Across machines: with your own server.
Setup, connecting Claude Code and CodexWorks.
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 runsThe 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 BuildNot yet; they can already use SOVREN from a terminal (sovren handoff …).
The ConductorBuilt; 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 · stopNot yet; they say so.

Help and fixes

IfThen
You want to know what a command doessovren --help or sovren help <command>
Something isn't workingsovren doctor checks everything and says how to fix it; sovren doctor --fix fixes what's safe
sovren isn't found right after installingpaste the one line the installer printed, or open a new terminal window
An agent failsSOVREN 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.