主权OS

简介

<p align="center"> <a href="https://github.com/Justin0504/Sovereign-OS/actions"><img src="https://github.com/Justin0504/Sovereign-OS/actions/workflows/ci.yml/badge.svg" alt="CI"/></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"/></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-green.svg" alt="Python 3.12+"/></a> </p>

<p align="center"> <img src="readme_images/sovereign_logo.png" alt="Sovereign-OS" width="720" style="max-width:100%"/> </p>

<p align="center"> <strong>Governance for an autonomous AI workforce — runs on your machine, on your keys.<br> Submit a goal: Sovereign-OS plans it, checks the budget, executes with built-in workers, and delivers a cryptographically verified result.</strong> </p>

<p align="center"> <em>Open source &bull; self-hosted &bull; bring your own keys &bull; no fund custody</em> </p>

<p align="center"> <a href="#quick-start">Quick Start</a> &bull; <a href="#architecture">Architecture</a> &bull; <a href="#features">Features</a> &bull; <a href="#deployment">Deployment</a> &bull; <a href="#configuration">Configuration</a> &bull; <a href="#custom-workers">Custom Workers</a> &bull; <a href="#docs">Docs</a> </p>

<p align="center"> <img src="readme_images/demo1.gif" alt="Sovereign-OS dashboard demo" width="760" style="max-width:100%"/> </p>

---

Overview

Sovereign-OS is not another chatbot wrapper or agent framework. It is an operating system for autonomous AI work: a governance layer that enforces budget, quality, and permissions before any token is spent or any task is executed.

The core contract is simple. One YAML file — the Charter — declares the agent's mission, spending limits, KPIs, and allowed capabilities. Everything else — planning, approval, execution, auditing, payment — flows from that file.

Charter → CEO (plan) → CFO (approve budget) → Workers (execute) → Auditor (verify) → Ledger (record)

The Ledger is append-only. The Auditor is cryptographically bound. Neither can be overridden at runtime.

---

Features

Governance - Charter-driven: mission, competencies, KPIs, fiscal boundaries — all in one YAML. - CEO (Strategist) decomposes natural-language goals into executable task plans with dependencies. Reactive: prune_to_budget sheds lowest-value tasks to fit a budget without breaking the dependency DAG; corrective_task builds a high-priority retry carrying the audit's failure reason and fix. - Profitability-first task selection — before spending any compute, an ingest screen (governance/economics.py) estimates a task's fully-loaded cost (LLM by category × complexity + settlement fee + gas) and skips anything that can't clear the margin floor. Stops the classic autonomous-agent failure mode where fees/gas turn shipped work into a net loss. Opt in with SOVEREIGN_PROFIT_SCREEN=true; tune with SOVEREIGN_{SETTLEMENT_FEE_RATIO,GAS_COST_CENTS,MIN_MARGIN_RATIO}. - Reactive self-repair — a task that fails audit is automatically re-run with the Auditor's reason + fix folded into its brief (SOVEREIGN_MAX_REPAIR_ATTEMPTS=N), recovering quality with no human in the loop. Only a fully-passing mission reaches delivery/settlement — a failed audit never gets submitted to a platform or charged. - CFO (Treasury) enforces max_task_cost_usd, daily_budget_usd, runway_days, and min_job_margin_ratio before any task runs. A runtime SpendCircuitBreaker adds fast-fail during a session — it halts the loop when cumulative spend hits a session ceiling, audits fail past a streak limit, or ROI collapses (the guard that stops runaway agent loops the pre-flight gates miss). Configure via SOVEREIGN_SESSION_CEILING_CENTS, SOVEREIGN_MAX_CONSECUTIVE_FAILURES, SOVEREIGN_ROI_FLOOR (all default off); watch it live on the dashboard Guardrails tab (session spend vs. ceiling, failure streak, ROI, one-click reset). - Permissions — TrustScore-gated capabilities (READ_FILES, WRITE_FILES, EXECUTE_SHELL, SPEND_USD, CALL_EXTERNAL_API), earned per category, with graduated autonomous-spend ceilings. High-risk grants use just-in-time leases: scoped to one task, bounded by TTL and use-count, auto-revoked on completion (grant_lease / use_lease / revoke_task_leases). Active leases and per-agent trust are shown live on the dashboard Guardrails tab. - Two dashboards, same guardrails — the web dashboard (Guardrails tab + per-task quality scorecard) and a Textual terminal Command Center (python -m sovereign_os.ui.app) both surface the CFO circuit breaker (session spend vs. ceiling, failure streak, ROI; press b to reset), active JIT leases, and the category-rubric breakdown streamed live under each audit verdict. - Prometheus metrics — all three guardrails export on /metrics for Grafana: breaker session spend/ceiling/ROI/trips, active JIT leases, per-agent trust, and per-category audit-quality histograms (overall + per rubric criterion). See docs/METRICS.md for the metric list and PromQL starter panels.

Execution - 16 built-in workers: summarize, research, reply, write_article, write_email, write_post, meeting_minutes, translate, rewrite_polish, collect_info, extract_structured, spec_writer, solve_problem, assistant_chat, code_assistant, code_review. - Verification-driven coding — the coding worker runs a harness-enforced loop (run_with_verified_tools): it won't accept "done" until the test suite actually passes. A premature answer bounces back with the failing test output and the model must fix and re-verify — code that can't reach green is marked tests_verified=false / success=false, so broken work never ships to a paid bounty. Gates only when execution is enabled (SOVEREIGN_CODE_EXEC_ENABLED); otherwise it's a no-op skip. - Multi-model: Strategist and workers can use different backends (e.g. GPT-4o for planning, Claude for execution). - Pluggable agent backends — for complex delivery a worker can delegate a whole task to a purpose-built coding agent (Claude Code, OpenAI Codex, Gemini CLI, Aider, or any headless CLI via a command template) instead of a single chat call. One stable AgentBackend seam; new agents plug in by config (SOVEREIGN_AGENT_BACKEND / SOVEREIGN_BACKEND_<CATEGORY>), dry-run until SOVEREIGN_AGENT_BACKEND_ENABLED=true. - MCP connectors in every worker — register MCP servers via SOVEREIGN_MCP_SERVERS and their tools appear inline in every worker's tool-use loop, next to built-ins like web_fetch. Any MCP-provided connector (DBs, search, SaaS, another agent over MCP) becomes callable mid-task with no code change — the universal connector layer both Claude Agent SDK and Codex speak. See docs/BACKENDS.md. - Dynamic worker loading: drop a Python file into sovereign_os/agents/user_workers/ — no registration boilerplate.

Auditing - Every task output is verified against Charter KPIs by the ReviewEngine. - Category-tuned analytic rubric: high-value deliverables are scored criterion-by-criterion on a rubric matched to the work type — coding gets correctness/completeness/robustness/relevance, writing gets clarity/voice, etc. — always ending in a safety criterion. Criterion order is deterministically shuffled per task to blunt LLM-judge positional bias. - Value-aware bar: higher-paid jobs must clear a stricter passing score; cheap tasks can skip the (relatively expensive) LLM judge. - AuditReport carries score, passed, reason, suggested_fix, sub_scores, and proof_hash (SHA-256 of inputs + output). Each job's delivery view renders a quality scorecard — the per-criterion rubric breakdown (bars per criterion, category label, overall score) so you can see why a deliverable passed or failed, not just the verdict. - Append-only audit trail (JSONL). Integrity verifiable offline.

Monetization & job queue - SQLite-backed job queue (Redis optional for multi-instance). - Stripe integration: set STRIPE_API_KEY and each completed job triggers a real charge; transactions appear in your Stripe Dashboard. - Auto-approval mode or manual review per job. - Ingest from any HTTP endpoint, Reddit (PRAW), Shopify, WooCommerce, or custom scrapers via the ingest bridge. - Webhook delivery: POST job result to any URL on completion.

<p align="center"> <img src="readme_images/job_delivery.png" alt="Job delivery result" width="340" style="max-width:48%"/>&nbsp; <img src="readme_images/stripe_dashboard.png" alt="Stripe Dashboard — completed charges" width="340" style="max-width:48%"/> </p> <p align="center">_{Left: job result delivered in the dashboard. Right: charges recorded directly in Stripe Dashboard.}</p>

Observability - OpenTelemetry tracing. - Prometheus metrics at GET /metrics: job counters, queue depth, task duration histograms. - GET /health returns config warnings (missing API keys, payment mode). - Structured JSON logs with correlation IDs.

Security - API key authentication (constant-time comparison). - Optional IP allowlist and per-IP rate limiting. - Job input validation (Pydantic v2). - No secrets in code; everything via environment variables.

<p align="center"> <img src="readme_images/block_case.png" alt="TrustScore gates" width="340" style="max-width:48%"/>&nbsp; <img src="readme_images/block_case_detail.png" alt="Permission gate detail" width="340" style="max-width:48%"/> </p> <p align="center">_{TrustScore-gated permission system — agents earn capabilities through passing audits.}</p>

---