An open protocol for portable, agent-backed personal software.
Read the spec · Read it on the web · Reference implementation · snugprotocol.org
Snug is an open protocol for user-built micro apps that think through their host's AI agent at runtime. A Snug app is a small sandboxed app (often a single HTML file) that a user creates through conversation with a product's AI assistant. At runtime the app exchanges versioned JSON envelopes with the host agent over a strict boundary — the agent is the app's mind; the app is a body. Apps reach the user's own services only through the host, inside a human-approved, host-frozen ceiling. Users own their apps and their data as one portable .snug file — a SQLite database they can open with ordinary tools, optionally sealed with a passphrase only they hold.
| SPEC.md | Specification 1.0 — the complete normative specification in one document |
| schemas/ | JSON Schemas for every message type — published byte-identical from the reference implementation |
| whitepaper/ | The whitepaper (PDF, edition 3 — the 1.0 edition): design rationale, threat model, security properties |
| implementations.md | Known implementations |
Specification 1.0 — NORMATIVE (2026-08-22). One document, six parts:
- The wire protocol — 13 frames (nine core plus the net and open-url pairs), the chat envelope, and rules R1–R7. The core has been published and stable since v0.1.
- The Portable User Database Format — storage schema 6,
.snugnaming, and theSNUGENC1protected (passphrase-sealed) form. - Connected applications — requirements, grants, credential custody, and the host executor: how apps reach a user's services without credentials ever entering the app or the LLM.
- Runtime contracts and the app chat surface — the compact per-app turn assembly that makes runtime thinking cheap enough for small local models.
- Linked-device connections — hosts that bridge a personal device session (e.g. WhatsApp) without an LLM in the loop.
- Conformance — what a host must, should, and may implement.
One section is explicitly provisional and so marked: §17 (standing approvals). All 14 schemas in schemas/ are byte-identical exports from the reference implementation.
Post-1.0, additive changes bump the minor; a change that breaks a conforming implementation bumps the major. v0.1 (the wire-protocol core) and the v0.2/v0.3 drafts were finalised into 1.0 — the retired draft filenames are pointer stubs; their full text lives in git history. Every change lands as a single commit traceable to its task in the reference repo.
This spec is maintained through the reference implementation's engineering process — protocol proposals and discussion happen in snugprotocol/snug issues/discussions; every spec change lands here as a single traceable commit. Direct PRs to this repo are welcome for typos and clarity only.
MIT · Security contact: security@snugprotocol.org
Maintainer: Jeetu Maker