Sovereign Code Runtime

Durable local work for ephemeral AI agents.

AI conversations disconnect, expire, and get replaced. Your local work should not.

Sovereign keeps Tasks, Agent ownership, permissions, messages, execution state, and evidence on your Windows computer, so another authorized Agent session can safely continue. ChatGPT or another MCP host supplies reasoning; Sovereign supplies the durable local operating environment.

中文说明 · Run the continuity demo · Architecture · Security · Contributing

Source preview. This repository publishes source code, not an announced binary release or proof of an installed system. Source CI does not certify native desktop behavior, and the full dependency-audit job may remain red for documented unresolved build dependencies. Read Security, the threat model, and dependency security, and see release evidence before treating a build as deployed.

ChatGPT Web is one supported connection path. Sovereign Code Runtime is an independent open-source project and is not affiliated with, endorsed by, or sponsored by OpenAI. OpenAI and ChatGPT are trademarks of their respective owners.

The problem Sovereign addresses

A web conversation is a poor place to store the authoritative state of long-running local work. It can disappear while a command is running, after files have changed, or before another Agent learns what happened.

Sovereign makes the work itself a local object:

• a Task has a persistent identity, owner, status, current step, progress, and conversation;

• an Agent is online only while a valid session lease is live;

• ownership changes invalidate stale sessions instead of letting two sessions act as the same owner;

• local actions remain constrained by workspace, permission, observation revision, and approval state;

• runs and audit receipts describe what actually happened, including failures and unknown outcomes;

• Renderer and Runtime candidates must pass controlled activation or cutover rules before becoming authoritative.

The design goal is simple:

Models and sessions may be replaced. Local work, authority, and evidence must not disappear with them.

Related MCP server: GPT Agent

Run the continuity demo

The demo uses the real Task registry, SQLite persistence, and session-lease implementation in an isolated temporary directory. It does not contact ChatGPT, start the Tunnel, read your Sovereign data, or mutate a project.

Requirements: Windows, Node.js 24+, and pnpm 10+.

pnpm install --frozen-lockfile
pnpm demo:continuity

Expected result:

Sovereign continuity demo
[pass] Session A created a durable local Task and checkpoint.
[pass] The Task and messages survived a registry restart.
[pass] Closing Session A preserved workflow state but removed its live lease.
[pass] Session B resumed the same Task from local state.
[pass] Session A was rejected after closure (POLICY_DENIED).

Result: durable work survived; stale session authority did not.

Use pnpm demo:continuity -- --json for a machine-readable report, or read the demo guide.

What remains local

Sovereign does not copy a model's private reasoning or automatically reproduce an entire ChatGPT transcript. Continuity comes from durable work facts and explicit handoff context.

How it fits

flowchart LR
    A[ChatGPT Web or another MCP host] -->|authenticated MCP session| B[Sovereign local runtime]
    B --> C[(Tasks, messages, leases)]
    B --> D[Policy, approvals, audit]
    B --> E[Files, Git, Terminal, Python, Browser, Desktop]
    B --> F[Optional secure execution and device endpoints]
    D --> E
    C --> B

The normal remote path is:

ChatGPT Web → OpenAI Secure MCP Tunnel → loopback Gateway
            → session / Task / permission policy → local tools and audit

The Gateway stays on 127.0.0.1, and Sovereign does not include a built-in model client.

What Sovereign is — and is not

Sovereign includes MCP tools and desktop automation, but those are execution surfaces. The differentiator is the persistent authority model around them.

Desktop application

The Windows workbench provides Home, Tasks, ChatGPT Connection, Task History, Terminal, Python, Browser, Desktop Control, Workflows, Capabilities, Approvals, Audit, and Settings surfaces.

To run the full desktop application from source:

1. Install Windows 10/11, WebView2, Node.js 24+, pnpm 10+, the Rust MSVC toolchain, and the .NET Framework C# compiler.

2. Run pnpm install --frozen-lockfile.

3. Run pnpm dev:desktop.

4. Select the exact folder the Agent may use.

5. Configure the official Windows tunnel-client, Tunnel ID, and runtime key in ChatGPT Connection.

6. Wait for Ready, then verify a read-only call before authorizing consequential work.

To locate existing verified build outputs without installing or launching them:

pnpm products
pnpm products:open

Windows users can also double-click open-products.cmd. Chinese console output is available through pnpm products:zh and pnpm products:open:zh.

For local build inventory and verification rules, see releases/README.md. A source checkout, packaged candidate, installed application, active Renderer, and active Runtime Host may all be different revisions.

Authority model

Remembered permissions are bound to the exact workspace. Workspace restore is a separate setting: enabling or disabling it never changes the active L1-L4 permission. L4 does not grant administrator elevation and does not remove schemas, containment, revision checks, identity checks, or audit.

Authority also has a freshness dimension:

• stale file hashes are rejected before guarded writes;

• stale browser and desktop observation revisions are rejected before actions;

• closed session leases cannot be reopened;

• an online Task owner cannot be replaced by another session;

• ownership changes fence the previous Agent identity;

• a candidate Runtime must drain accepted work, establish a checkpoint, acquire a fencing generation, and pass canary checks before durable promotion;

• unknown execution outcomes are not silently retried as success.

Capabilities

The live manifest is authoritative. Discover it through MCP tools/list, the authenticated Gateway /v1/manifest, or:

capabilities.search
capabilities.describe
capabilities.execute
capabilities.snapshot
client.catalog_status

Current capability families include workspace and Git operations, managed Terminal and Python runs, browser automation, revision-bound Windows desktop control, workflows, Tasks, Agent coordination, context retrieval, optional semantic-code tools, and optional secure execution.

Read capability discovery, tool packs, Task and Agent Hub, and Agent coordination for the exact contracts.

Notifications

Sovereign has no notification milestones, content-hash deduplication, or per-domain/rolling notification buckets. Notifications are semantic signals for meaningful work, completion, or operator attention; routine successful non-workflow runs do not require an automatic notification.

Security boundaries

PowerShell, ConPTY, Python (including -I), browser evaluation, and normal desktop control run with the current Windows user's rights; they are not OS sandboxes. Only execution explicitly routed through the optional secure-execution pack uses its reviewed Docker boundary.

Secure Desktop, credentials, passkeys, OTPs, CAPTCHAs, and elevation consent remain human handoffs. Persisted Tunnel keys and proxy settings use Windows DPAPI-protected ciphertext, while plaintext remains in trusted-process memory. Review the threat model before enabling consequential authority.

Current maturity

Implemented source paths include the Tauri/WebView2 shell, Node Runtime Host, MCP Gateway, workspace-bound L1-L4 policy, native approvals, audit, persistent Tasks and messages, session leases, Agent coordination, Tunnel supervision, Host Guardian recovery, capability discovery, Renderer update management, and Runtime candidate cutover machinery.

Important boundaries remain:

• this repository is still presented as a source preview rather than an announced public binary release;

• full application restart does not yet provide general interrupted-task replay;

• there is no offline remote task queue or pre-login Windows service;

• ordinary Terminal and Python execution are not OS-isolated;

• public production trust material and Authenticode signing are not implied by the update mechanisms;

• Android and session-local computer endpoints require their own real-device and environment acceptance.

The documentation deliberately distinguishes design, test success, packaged candidate, installation, activation, and observed running behavior.

Develop

pnpm install --frozen-lockfile
pnpm typecheck
pnpm test:demo-continuity
pnpm dev:desktop

Useful locations:

Read the development guide and repository layout before changing, packaging, or altering installed state.

Contribute

Contributions are most useful when they strengthen a documented invariant, improve the first-run path, add deterministic compatibility evidence, or make authority state easier to understand.

Start with CONTRIBUTING.md. Bug and feature templates ask explicitly whether a change affects workspace containment, Task ownership, session leases, approvals, unknown outcomes, or Runtime authority. Security reports belong in the private channel described by SECURITY.md, not in a public Issue.

Release evidence and boundaries

Build success, package verification, installation, activation, and observed running behavior are separate facts. A dry run, Renderer smoke test, portable smoke test, or valid manifest does not prove that an NSIS installation succeeded or that a candidate is currently active.

Renderer updates, Runtime Host updates, and full-application restarts have different coordination rules. Use the applicable Renderer, Runtime Host, or application restart guide before changing running state. Release artifacts should be attached to GitHub Releases rather than committed to source history.

License

Sovereign's original source code and documentation are licensed under the Apache License, Version 2.0. Third-party components retain their own licenses; see NOTICE and THIRD_PARTY_NOTICES.md.