Core Concepts

The Capsule execution model operates with CLI, Runtime, and Desktop having separated responsibilities, based on declarations in capsule.toml.

What is Capsule

Capsule is a package format for .capsule (app distribution) or .sync (self-updating data). Both are ultimately validated and executed based on declaration files.

Format	Primary Purpose	Reference Spec
`.capsule`	App/tool distribution, runtime selection, signature verification	`CAPSULE_SPEC.md`
`.sync`	Immediate payload display + TTL updates + (future) Vault encryption	`SYNC_SPEC.md`

Manifest (capsule.toml)

Required fields are schema_version, name, version, type, default_target, targets. Additional declarations: metadata, build, isolation.

schema_version = "0.2"
name = "example-app"
version = "0.1.0"
type = "app"
default_target = "cli"

[targets.cli]
runtime = "source"
entrypoint = "python main.py"

[targets.static]
runtime = "web"
entrypoint = "index.html"
public = ["index.html", "assets/**"]

Lifecycle: Tasks and Services

LIFECYCLE_SPEC v1.2 explicitly separates terminating processes as [tasks] and resident processes as [services]. Nacelle executes them as a DAG (Smart Build, Dumb Runtime).

[tasks.install]
cmd = "npm ci"

[services.app]
cmd = "npm start"
depends_on = ["install"]
readiness_probe = { http_get = "/health", port = "APP_PORT" }

[lifecycle]
run = "app"

Runtime Routing

ato open <path> [-t <label>] resolves runtime from selected target.

Condition	Selected Runtime
`-t <label>` specified and `targets.<label>.runtime = web`	Web (static server)
`-t <label>` specified and runtime is not `web`	Source/Wasm/Oci by runtime
`-t` omitted	`default_target`

IPC Roles (v1.1)

The key change in IPC v1.1 is the transfer of Broker responsibilities from nacelle to ato-cli.

ato-cli: Service resolution, RefCount, Token management, Schema validation, DAG integration

nacelle: Sandbox Enforcer. Does not interpret IPC content, only handles isolation

ato-desktop: HostBridge, mode switching, User Consent dialogs

Trust Model

Minimum Trust UX is TOFU + Fingerprint pinning + Revocation list application. When signature mismatch occurs, the policy requires re-verification rather than temporary allowance.

Save fingerprint on first connection (~/.capsule/trust_store.json)
Petname is optional but linked to trust store’s key_id
Key rotation maintains short previous_key co-existence period

Source specs: CAPSULE_SPEC, LIFECYCLE_SPEC, CAPSULE_IPC_SPEC, TRUST_AND_KEYS.