Policy reference

Hostwright policy is local and deterministic. It explains why a planned input is allowed, warned, or blocked before any supported mutation path can run. The conceptual overview is in Policy engine.

Decision shape

Every policy decision includes:

• category: the policy area, such as port, mount, image, secret, cleanup, or accelerator;
• reasonCode: a stable machine-readable reason;
• severity: allow, warning, or blocker;
• message: human-readable explanation;
• remediation: operator guidance;
• stableDetailKey: deterministic ordering and comparison detail.

Current defaults

• Host publishes remain localhost-first; broad bind addresses are blocked.
• Duplicate desired host ports and observed non-target host-port conflicts are blocked.
• Privileged host ports produce warnings in planning and are rejected by the create path before mutation.
• Host-root and parent-traversal mount sources are blocked.
• Secret-like environment values are redacted from plans; unresolved secret references block mutation.
• Cleanup deletes only exact Hostwright-owned non-running eligible containers after dry-run token confirmation.
• Unsupported manifest fields, secure exposure, broad lifecycle actions, and accelerator requests fail closed.
• Stack-file import maps unsupported fields to stable policy reason codes.
• Advisory scheduling consumes policy decisions for explanations and scores without changing the gates.
• Extension declarations are evaluated as local data: built-in or reviewed-local non-mutating declarations can be allowed only when every required boundary (RuntimeAdapter, state, policy, redaction, audit, explicit paths, ownership, confirmation, no runtime mutation) is declared. Third-party, untrusted, runtime-mutation, state-write, networking, tunnel, secret-resolution, and accelerator declarations fail closed.
• Team policy profiles are explicit local opt-in, versioned, and auditable. Operational profiles can only add stricter digest or manifest-review requirements. Approval records authorize one exact bound mutation; they never weaken required gates.

Evaluation boundary

Policy evaluation is a pure, in-memory function. It reads the plan and profile data passed to it and returns typed decisions. Every side effect (runtime commands, SQLite reads and writes, registry calls, telemetry, plugin execution) belongs to the commands that consume those decisions, each behind its own gate.

Team policy boundary

Team profiles apply when an operator supplies a path with --team-profile. Profiles can only make requirements stricter, and approval records authorize one exact bound mutation while the hard-coded safety gates continue to apply. The operational flow, JSON schemas, and audit records are documented in Team workflow.