Safety model

Infrastructure tooling earns trust by being predictable when things go wrong. Hostwright’s safety posture is deliberately conservative, and unlike an aspiration, it is enforced by the command surface itself: there is no way to mutate the runtime except through two explicit, confirmed gates.

Principles

• Plan before mutation. apply recomputes the plan against a live observation and refuses to run unless your --confirm-plan <hash> matches it.
• One action per apply. Exactly one executable action runs per invocation — create a missing service, or a restart-policy-allowed managed start or restart. Zero executable actions refuses; more than one refuses.
• Dry-run before deletion. cleanup --dry-run classifies every candidate and prints an exact confirmation token. Only --confirm-cleanup <token> with that token deletes anything.
• Intent before mutation. Operation intent, recovery groups, and checkpoints are persisted to the explicit state database before the runtime is touched.
• Conservative validation. Unsafe or ambiguous manifests are refused, not guessed at — see the policy engine.
• Ownership-tracked cleanup. No broad garbage collection. Cleanup touches only resources Hostwright can prove it owns.
• No secret leakage. Plans, events, logs, state rows, and errors carry redacted values only.

The apply gate, concretely

hostwright apply refuses mutation when — among other cases — the state database or plan hash is missing or mismatched, observation fails, the plan has blockers, zero or multiple executable actions exist, a create action uses mounts or privileged ports or broad bind addresses, the local image cannot be confirmed, or another operation still holds an active lease. Created port bindings are published to 127.0.0.1 explicitly. A managed restart additionally requires exact Hostwright ownership, live observed running state, and a fresh persisted unhealthy health result.

An interrupted operation can reuse its plan only when the persisted checkpoint proves runtime execution never began. Anything ambiguous stays blocked and is reported by hostwright recovery.

Ownership

Hostwright distinguishes resources it created from resources you created by hand. Hostwright-created containers carry versioned identifiers and exact ownership labels, mirrored by ownership records in the state store. The rule is strict: cleanup never deletes a resource it cannot prove Hostwright owns.

Cleanup classifications from the dry run: eligible, ambiguous, stale, running (never deleted), unknown, blocked, and never-delete. Only eligible — an exact Hostwright-owned created/stopped/exited container covered by the current token — is ever deleted. Images, volumes, networks, and unmanaged containers are never touched, and broad flags like --all or --force are never used.

Secrets

Secrets are not committed into manifests. Plaintext sensitive keys under env fail validation; secret values enter only through keychain:// references resolved at the last moment before a confirmed create.

User-space first

Hostwright does not install privileged helpers, launch agents, or services. Any future operation that would require elevated privilege needs a threat model first — see Security and safety.