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

Every mutating command requires an explicit confirmation bound to a specific, re-observed reality: a plan-hash-confirmed lifecycle command (up, down, run, start, stop, restart, rm, update, or apply as its compatibility alias), plan-hash-confirmed image or volume deletion/pruning, token-confirmed cleanup, a confirmed runtime-provider migration, or the explicitly confirmed benchmark path. Nothing mutates the runtime as a side effect of a read command, and no command accepts a broad flag like --all or --force. See Limitations for what is outside the command surface entirely.

Restart policy state can block the managed start/restart paths through backoff, operator hold, restart.policy: no, and crash-loop protection. Operation recovery records support hostwright recovery resume and hostwright recovery rollback, but both require a fresh confirmation and re-observe current reality before acting. Recovery never replays a stale intent automatically.

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 typed secretEnv references.
• Reference labels are themselves redacted, because service/account names reveal local context.
• hostwright secret writes only to Hostwright-owned Keychain items, interaction-disabled and excluding synchronizable items; it never touches an item it does not own.

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: a stable content identifier the rest of policy can build on. On its own it does not contact a registry, resolve a tag, or judge whether a digest is trustworthy.

Layered on top of it, four optional manifest policies add real, offline, signature-based evidence checks before a lifecycle mutation: imageTrust (Sigstore signature verification against declared authorities), imageSBOM (required SBOM evidence in a declared format), imageVulnerability (a signed vulnerability report evaluated against severity/exploitability/fix thresholds, with time-boxed exceptions), and imageProvenance (a signed in-toto/SLSA build-provenance statement checked against declared builders and signers). Each is off by default; declaring one makes its evidence mandatory before execution. See the policy sections in the manifest reference. Deciding which authorities, issuers, and builders to trust remains your call. Hostwright verifies against what you declare, and declares nothing on your behalf.

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.