Host runtime CLI + daemon (`tappass-host`)

Host runtime CLI + daemon (tappass-host)

What it does: What runs on the agent's machine to apply layered config and launch the agent process.

1. Vision context

tappass-host is the daemonized variant of tappass exec from the gateway concept. Where tappass exec wraps an interactive dev tool one-shot, tappass-host hosts long-running agentic services — receiving signed sync, applying the layered keyring, launching the agent.

It owns the machine identity on the host. The agent runs unprivileged, under a different UID, with the keyring mounted read-only — the mechanical foundation of "the agent cannot escalate" (Q13).

2. Functional specification

Full command surface in architecture §13.4 and §14.2. The entrypoints:

• init <name> --enroll-url <url> — consume bootstrap, establish mTLS to TapPass, create sandbox state dir.
• start <name> --agent <pkg> — apply layers in sequence; exec agent entrypoint inside the prepared sandbox.
• stop <name> / status / inspect / logs / shell
• daemon — long-running sync receiver.

3. Technical design

Lives at tappass-host/. Python package + systemd unit. Uses OpenShell primitives from tappass/sandbox/ for kernel-layer enforcement. Implements layer-application sequence via per-layer adapters defined in q09-rings-and-cross-cutting/ components.

Shares OpenShell core with tappass exec; differs in lifecycle (daemon vs. one-shot wrapping).

4. Definition of done

• All acceptance_criteria pass.
• End-to-end test: bootstrap → init → start → agent runs → operator changes policy → host receives sync → keyring updated atomically → agent observes.
• Failure tests: bootstrap consumed twice → second fails; sync signature invalid → payload dropped, audit logged.
• systemd unit ships with the package.

5. Coordination notes

With every layer applier in q09-rings-and-cross-cutting/: we invoke them in sequence. Their interface is stable; we own the orchestration.

With agent-client-sdk: we exec agents that import this SDK. Coordinate on the env-var contract (TAPPASS_KEYRING_PATH).

Open questions:

• (Q) Which OS distros do we ship support for in v1? Lean: Linux-amd64 + Linux-arm64 ship in v1; macOS/Windows graceful degradation (kernel layer disabled with warning); native macOS Endpoint Security in v2 if customer demand.
• (Q) Multi-sandbox per host — concurrency limits? Lean: soft cap (8) configurable; OOM is the real backstop.

6. Out of scope

• Authoring policy (operator-cli).
• Reading the keyring (agent-client-sdk).
• Auto-discovery of agents (concept-stage; not in scope here).