# Sovereign Code Runtime

**Source preview:** this checkout is not an announced binary release or an installed-state verification. Review [security and reporting](SECURITY.md), [dependency findings](docs/dependency-security.md), and [contribution guidance](CONTRIBUTING.md). Source CI does not certify native desktop behavior; the complete dependency-audit job checks the development/build graph separately from the production-only audit.

Sovereign lets a **ChatGPT Web conversation operate a Windows computer through MCP**. ChatGPT supplies the model and conversation; Sovereign supplies local tools, permissions, task state, and audit evidence. The installed application has no dependency on Not-Code or Not-Meta accounts or services and does not include a built-in model client.

**[Ready-to-use builds](releases/README.md)** · **[Documentation](docs/README.md)** · **[Development](docs/development.md)** · **[Android preview](apps/android-agent/README.md)**

## Use Sovereign

Double-click `打开成品.cmd` or run `pnpm products` to locate existing builds; this does not install or start SO. See the [release guide](releases/README.md) for selection and verification details. Source checkouts, packaged candidates, and the installed application can be different revisions; a newer file is not proof that it is running.

1. Start Sovereign and authorize the folder the agent may use.
2. Make the official Windows `tunnel-client` available on `PATH`, select it locally, or set `SCR_TUNNEL_CLIENT_PATH` before launch.
3. In **ChatGPT Connection / ChatGPT 连接**, enter the OpenAI tunnel ID and runtime key, select the needed permission level, and press **Start connection / 启动连接**.
4. Wait for **Ready**, then configure the ChatGPT custom app to use that tunnel ID. Verify a read-only tool call before continuing the task.

The normal connection is:

```text
ChatGPT Web → OpenAI Secure MCP Tunnel → loopback Gateway
            → permission and workspace policy → local tools and audit
```

The desktop Gateway stays on `127.0.0.1`. The connector receives its local Bearer through its child environment, not its command line. Persisted tunnel keys and proxy settings use Windows-DPAPI-protected ciphertext; plaintext stays in trusted-process memory. Optional control-plane proxies do not proxy local MCP traffic. Connection recovery still requires a working route to the official Tunnel service.

For proxy/failover, post-sign-in remote hosting, and recovery, use [Remote Host](docs/remote-host.md) and [control-plane failover](docs/control-plane-failover.md). A trusted HTTPS `/mcp` bridge is an optional alternative; without one, **Copy MCP connection** targets only the local Gateway. Copied bundles contain a credential and have a bounded clipboard lifetime. Rotating that credential disconnects existing sessions and stops the active tunnel.

## Capabilities and permissions

The workbench provides Home, Tasks, ChatGPT Connection, Task History, Terminal, Python, Browser, Desktop Control, Workflows, and Settings. It combines project/task progress with managed runs and bounded activity; completed audit receipts remain the evidence for actual outcomes.

Discover the current tools through MCP `tools/list`, the authenticated Gateway `/v1/manifest`, or `capabilities.search` and `capabilities.describe`. The live manifest is authoritative; optional packs and installed revisions change availability. See [capability discovery](docs/capability-catalog.md), [tool packs](docs/tool-packs.md), and [task coordination](docs/task-coordination.md).

| Profile | External tool behavior |
| --- | --- |
| L1 Observe | Read-only observation tools. |
| L2 Workspace | L1 plus contained workspace writes, local Git writes, fixed validation, and run cancellation. |
| L3 Consequential | L1/L2 directly; consequential calls require fresh native approval. |
| L4 Bypass | Declared tools without Sovereign approval prompts, after explicit local confirmation. |

Remembered permissions are workspace-bound. Restoring L4 requires a valid current-user DPAPI grant for that exact workspace. L4 does not grant administrator elevation or remove schemas, containment, revision checks, or audit. Workspace restore is a separate setting: enabling or disabling it never changes the active L1-L4 permission.

PowerShell, ConPTY, Python (including `-I`), browser evaluation, and desktop control run with the Windows user's rights and are **not OS sandboxes**. Only execution explicitly routed through the optional [secure-execution pack](docs/secure-execution.md) uses its reviewed Docker boundary. Secure Desktop, credential entry, elevation, passkeys, OTPs, and CAPTCHA remain human handoffs. See the [threat model](docs/threat-model.md).

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

## Develop

From the repository root, with Windows 10/11, WebView2, Node.js 24+, pnpm 10+, the Rust MSVC toolchain, and the .NET Framework C# compiler available:

```powershell
pnpm install --frozen-lockfile
pnpm dev:desktop
```

This starts a development shell. For targeted validation, packaging, and authorized deployment, follow [development and release validation](docs/development.md). Choose checks for the changed behavior; the aggregate commands already include overlapping tests and build steps.

| Location | Responsibility |
| --- | --- |
| `apps/desktop-tauri` | Primary Tauri/WebView2 shell, Rust authority boundary, packaging, and Guardian. |
| `apps/desktop/src/renderer` | Shared workbench UI used by **both Tauri and Electron**. The rest of `apps/desktop` also contains the legacy Electron host and native helper. |
| `apps/runtime-host` | Node sidecar hosting the shared control plane and Gateway. |
| `apps/gateway` | MCP transport, live catalog, and optional headless entry point. |
| `packages/control-plane` | Settings, permissions, tasks, tunnel supervision, and runtime lifecycle. |
| `packages/runtime-core`, `packages/windows-adapter`, `packages/toolkit` | Policy and ledgers; Windows primitives; tool definitions and dispatch. |
| `apps/android-agent` | Independent Gradle Android preview; see its README for this checkout's actual status. |

[Architecture](docs/architecture.md) explains the execution paths. [AGENTS.md](AGENTS.md) governs repository work; load a topic's detailed guide only when that task needs it.

## Release evidence and boundaries

Build success, signed-package verification, installation, activation, and observed running behavior are separate results. Preserve user settings and databases during deployment. A dry-run, renderer smoke, or portable smoke does not prove an NSIS installation succeeded. Installation/restart smoke replaces or stops applications and requires authorization for those effects.

Renderer updates, Runtime Host updates, and full-application restarts have different compatibility and coordination rules. Use the applicable [renderer](docs/renderer-hot-updates.md), [Runtime Host](docs/runtime-candidate-updates.md), or [restart](docs/application-restart-updates.md) guide before changing running state. Signed-update support requires provisioned trust material; it does not imply an enabled downloader or trusted release feed. Development executables are not Authenticode-signed.

The project is a clean-room implementation: it does not copy proprietary Not-Code implementation, private schemas, credentials, user data, branding, or service logic.

## License

Sovereign's original source code and documentation are licensed under the [Apache License, Version 2.0](LICENSE). Copyright 2026 Sovereign Code Runtime contributors. Third-party components retain their own licenses; see [third-party notices](THIRD_PARTY_NOTICES.md). This license does not grant rights to third-party services, credentials, or trademarks.