Sovereign Agent

The executable textbook for Zero-Employee Organizations.

Sovereign Agent 1.x is a small Python reference implementation for learning how an outcome becomes governed work performed by accountable actors. Production organizations graduate to Zero Employee.

Install and run with uv

uv is the supported way to install and run sovereign-agent. Try it without installing anything permanent:

uvx sovereign-agent@latest doctor
uvx sovereign-agent@latest demo store --mode simulated --root /tmp/first-shift

(@latest makes uv refresh its cached tool environment, so you always get the current release.)

Or install the CLI onto your PATH:

uv tool install sovereign-agent
sovereign-agent doctor

(Plain pip install sovereign-agent still works in any Python 3.14 environment if you prefer it.)

The 1.x API intentionally replaces the v0.7 fleet framework. To keep using that framework: uvx "sovereign-agent<1".

Educational development install

Python 3.14 is required; uv provides it automatically.

uv sync
uv run sovereign-agent doctor

Expected result:

Sovereign Agent doctor
  Python:   3.14.x OK
  Pydantic: 2.x OK
  Network:  not required
  Tokens:   not required
  Providers:
    scripted available (streaming)
    claude   missing executable
    ...
Ready for the offline curriculum. Live providers are optional.

Chapter 0 is runnable as a manually dispatched store shift (no Pulse):

uv run sovereign-agent demo store --mode simulated

See book/ch00_first_shift and book/ch03_actor_is_not_a_model.

Product vocabulary

Thing	Canonical word
Package and CLI	`sovereign-agent`
Control loop	`supervisor`
Installed OS hosting	`service`
Proactive wake	`pulse`
Liveness proof	`heartbeat` (records the runtime was alive; never creates work)
Intelligence CLI	`provider`
Governed identity	`actor`

An actor is not a model. Every provider receives the same governed assignment envelope and must emit a valid terminal event and write the exact ActorReport. A zero exit without both is a failed receipt. Cursor's --workspace is directory selection, not sandboxing; isolation belongs to Sovereign Agent's disposable workspace.

Provider subprocesses receive only base process variables plus documented credential allowlists: Claude (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN), Codex (CODEX_API_KEY), and Cursor (CURSOR_API_KEY). Other parent secrets are not forwarded.

Unit 1 gates

python -m pytest -q
python scripts/verify_runtime_dependencies.py
python scripts/verify_source_budget.py
sovereign-agent --help
sovereign-agent doctor

See the educational reset ruling and v0.7 migration guide.

Project resources

Development Status
- 4 - Beta
Intended Audience
- Education
Operating System
- OS Independent
Programming Language
- Python :: 3
- Python :: 3.14
Topic
- Education
Typing
- Typed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sovereign_agent-1.2.0.tar.gz (201.2 kB view details)

Uploaded Sep 2, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sovereign_agent-1.2.0-py3-none-any.whl (121.9 kB view details)

Uploaded Sep 2, 2026 Python 3

File details

Details for the file sovereign_agent-1.2.0.tar.gz.

File metadata

Download URL: sovereign_agent-1.2.0.tar.gz
Upload date: Sep 2, 2026
Size: 201.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sovereign_agent-1.2.0.tar.gz
Algorithm	Hash digest
SHA256	`caf022d5f545234f25daf74a680a308cf4ad7986aab7060b61f334a2a4d74558`
MD5	`59af62bf49adfdd278748384da762114`
BLAKE2b-256	`eeb0bf90f3dcf3cabd0242646e3b70af8344f3f76b9066293394d0dab296ea2c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for sovereign_agent-1.2.0.tar.gz:

Publisher: publish.yml on profrodai/sovereign-agent

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: sovereign_agent-1.2.0.tar.gz
- Subject digest: caf022d5f545234f25daf74a680a308cf4ad7986aab7060b61f334a2a4d74558
- Sigstore transparency entry: 2687610145
- Sigstore integration time: Sep 2, 2026
Source repository:
- Permalink: profrodai/sovereign-agent@093b392541f115f08b1f6fc0faa421cca1b4a8a3
- Branch / Tag: refs/tags/v1.2.0
- Owner: https://github.com/profrodai
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@093b392541f115f08b1f6fc0faa421cca1b4a8a3
- Trigger Event: push