# pamd: persistent local audio service

Protocol v1. `pam` starts pamd on demand; the PAM instrument hosts inference in-process and does not start or use this service. Both share model files protected by nonblocking process locks. Native and TypeScript clients are implementation components, not a supported external SDK.

Use `pam daemon up`, `pam daemon status --json` and `pam daemon down` for lifecycle. The owner-only `daemon.json` discovery file under the PAM data directory supplies the loopback address, port, process ID, epoch and token path. Authenticate with the per-install 256-bit token (43 base64url characters); never put it in logs or publish it. Discovery and token files use POSIX mode 0600.

The TCP protocol uses a four-byte network-order length followed by JSON (maximum body 1 MiB). Requests contain major, minor, id, method and params. Start with `system.authenticate`, then inspect `system.capabilities` and health. Reject mismatched epochs before reusing handles. Only documented available methods may be called.

Catalogue install/remove and render jobs return handles. Inspect job status and events until terminal state; cancellation is explicit and results survive client disconnects. Models loaded through model.load remain owned by the daemon until unloaded. Streams use a separate negotiated shared-memory data plane; do not invent transport IDs or pass arbitrary artifact paths.

Errors include authentication/version failures, not_admitted, unavailable, model_crashed, cancelled and model_in_use. The latter means a loader or another writer holds the physical model-file group. Workers retain read leases; installs and deletions take exclusive leases. Shared Magenta resources remain intact while an installed sibling needs them.

`pam mcp` relays to daemon-hosted MCP sessions with file tools, model tools and controls for a selected running PAM instance. Plugin control requires the installed bundled runtime and PAM's existing MCP Bridge toggle. SA3 and Magenta adapters support local generation, and Magenta supports streaming; inspect model readiness and install the required model files and runtime dependencies.

Headless `preset render`, `fx`, `audio master` and `dj set` run in isolated workers and require a PAM licence or active trial. Preset metadata and referenced song presets also enforce desktop pack ownership; factory presets need no separate pack purchase. Jobs retain results and cancellation across client disconnects.

See the [versioned protocol contract](/agents/protocol/v1.json), [CLI command reference](/agents/commands/v1.md) and [setup](/agents/setup.md). pam, pamd and pamd-worker install with PAM’s command-line tools ([setup](/agents/setup.md)). Per-client installed-package and file-delivery acceptance remains open. No speed or memory improvement is claimed without measurements.