hugger-mugger/soth

1. Repository shape. This is a Rust workspace centered on a local edge-governance runtime, with supporting CLI tooling, shared domain crates, optional cloud sync, language bindings, and two extension ecosystems. The main architectural boundary is between the on-device control plane and the optional SOTH Cloud backend.

2. Primary runtime: soth-cli + soth-proxy. soth-cli is the operator-facing entrypoint. It installs the local CA, starts/stops the proxy daemon, manages config, enrollment, events streaming, and self-update. soth-proxy is the long-running network interceptor and enforcement engine.

3. Traffic interception boundary. The proxy sits between AI agents and external services. It selectively terminates TLS for configured AI-provider domains and transparently tunnels everything else. It handles HTTP(S), streaming responses, and other agent-facing transports, while keeping unrelated traffic out of the trust boundary.

4. Decision pipeline inside the proxy. Requests flow through staged gating logic before forwarding: TLS/origin checks, app-origin validation, whitelist/blacklist checks, app-type checks, and host-origin checks. That gating layer decides whether traffic is allowed, blocked, or specially handled, and it is the main policy enforcement seam.

5. Shared domain model. soth-core holds the common primitives used across the system: identities, requests, sessions, observations, policy, providers, telemetry, crypto, and normalized event types. soth-api-types defines the serialized API/wire shapes and conversions, so the proxy, sync layer, bindings, and cloud-facing code all speak the same contract.

6. Classification and detection pipeline. soth-classify provides a multi-stage classification pipeline used to infer use cases, volatility, anomalies, policy signals, and telemetry enrichment, with optional ONNX-backed models. soth-detect contains deterministic detection helpers for sensitive/code/stream parsing and replay logic. Together these form the “understand what the traffic means” layer that feeds policy and observability.

7. Policy is a separate engine. soth-policy isolates policy evaluation, including synchronous policy logic and corpus-driven tests. This keeps enforcement decisions distinct from transport handling and makes policy a pluggable, testable subsystem rather than ad hoc code inside the proxy.

8. Local storage and observability. soth-telemetry is the local SQLite-backed store for captured events. The proxy also has its own session store and observability modules for redaction, tracing, and local state. In standalone mode, this local store is the system of record; nothing needs to leave the machine.

9. Optional cloud sync path. soth-sync is the bridge to SOTH Cloud. It handles enrollment, config and registry pulls, body uploads, heartbeat, retry/outbox semantics, and telemetry replay. This is an opt-in pipeline that moves locally captured data to the managed dashboard/fleet backend; the proxy remains fully functional without it.

10. Bundle and update infrastructure. soth-bundle and the bundle-related modules in core/proxy manage signed, versioned bundle artifacts used for detection/gating/classification data. The CLI also has update/download/swap code and a sidecar updater for replacing binaries safely across OSes. This is how rules/model/data updates flow into the runtime without coupling them to the application code.

11. Extension layer for agent ecosystems. extensions/code parses and adapts events from specific AI coding tools such as Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi Agent, and Windsurf, turning tool-specific events into a common hook/event model. extensions/historian backfills and normalizes historical records from JSON, JSONL, or SQLite sources. These are integration boundaries rather than core enforcement logic.

12. Language bindings and SDKs. The repo exposes native bindings for Node (soth-node), Python (soth-py), Go (soth-go), and an edge/browser wrapper (soth-edge). The bindings layer is where ecosystem-specific instrumentation and integrations live, while the core Rust crates remain the authoritative implementation. Cross-language conformance tests protect that boundary.

13. Validation and release scaffolding. The workspace includes contract, corpus, and FFI conformance tests across proxy, detect, telemetry, sync, bindings, and extensions. CI workflows and the ops/scripts directories support signed releases, installation, and operational rollout, but the runtime architecture itself is organized around the local proxy + store + optional sync model.