Security and safety

Hostwright is in active development and not production ready. This page is the operational counterpart to the safety model: what the boundaries mean when you run the tool.

Mutation boundaries

Supported mutation is intentionally narrow: one plan-hash-confirmed create-missing-service, one restart-policy-allowed managed start, one managed restart of an exact Hostwright-owned running/unhealthy service, exact token-confirmed cleanup deletes, and the explicitly confirmed benchmark path. Broader lifecycle operations are outside the current surface. See Limitations.

Restart policy state can block the managed start/restart paths through backoff, operator hold, restart.policy: no, and crash-loop protection. Operation recovery records are audit and guidance only; inverse operations always require a new confirmed plan.

New runtime resources use collision-resistant v2 identifiers and exact ownership labels. Ownership is never inferred from a Hostwright-looking name.

Cleanup safety

Destructive cleanup requires all of: explicit --state-db, a dry run first, a matching token, a Hostwright ownership record, live observation, an exact owned identifier, matching project/service, and a created/stopped/exited lifecycle. Images, volumes, networks, Apple builder resources, base images, and unmanaged containers remain untouched.

Secrets and redaction

Execution values are kept separate from display and persistence values: runtime command construction receives the manifest value, while output, logs, state payloads, events, plans, and failure messages are redacted.

• Plaintext credential-like keys in env are rejected: use secretEnv with keychain:// references.
• Keychain reference labels are themselves redacted, because service/account names reveal local context.
• The live macOS Keychain is not used by default; the opt-in backend is read-only, interaction-disabled, and excludes synchronizable items.

Redaction is heuristic

Do not place plaintext credentials in manifests, logs, examples, fixtures, or issue reports. Diagnostic bundles are local-only and redacted, but can still contain project names, paths, hostnames, and identifiers. Review before sharing.

Untrusted manifest input

Treat third-party hostwright.yaml files as untrusted. The restricted parser rejects unsupported YAML, orchestrator fields, unsafe mount sources, and unsafe env keys. Trust decisions stay with you after validate and plan pass: inspect image names, port publishes, environment values, volume paths, and health probe commands before any confirmed apply or daemon run.

Image trust

imagePolicy: require-digest is local string validation only. It gives Hostwright a stable content identifier to require; it does not contact registries, resolve tags, pull images, verify signatures, inspect SBOMs, scan vulnerabilities, or prove provenance. Deciding which registries, publishers, and digests to trust remains your call.

Network exposure

Ports use "host:container" with no bind-address field. Hostwright-created publishes bind to 127.0.0.1 explicitly. Broad bind addresses (0.0.0.0, ::) are blocked in desired state, and observed non-target services on the same host port block mutation planning.

Team, extension, and control-surface boundaries

• Team workflow is explicit local profile and approval data only; profiles can only make requirements stricter.
• Extensions are declaration-only: Hostwright evaluates typed declarations but does not load, install, distribute, or execute plugins.
• Future GUIs must go through Hostwright command contracts preserving the same gates; nothing may call Apple container, SQLite, or the RuntimeAdapter directly.

Security-sensitive scope

Several security-sensitive capabilities are outside the current surface, including trusted distribution (signing, notarization, SBOM, provenance), a launch agent with unattended operation, DNS and tunnel management, and plugin execution. Limitations lists the complete boundary.

Report security issues per SECURITY.md in the core repository.