1ctl v1 Contract

The v1 contract is the behavior users can rely on from the current 1ctl surface.

Deployment contract

• 1ctl deploy defaults to managed cloud capacity.
• Owned machines are selected only with --machine or --machine-tag.
• --cpu sets CPU request.
• --memory sets memory request and memory limit.
• Memory requires Mi or Gi.
• --image skips cloud build.
• --wait defaults to --wait-mode application. It succeeds only after reconciliation is current, the workload is available, and application readiness is verified; replica counts and generic reachability alone are insufficient.
• --wait-mode workload is the explicit, warning-producing compatibility opt-in. It waits only for current reconciliation plus an available workload; application readiness is not verified.
• --health-path /health or [checks].health_path can provide application verification only after the public route is available and the HTTP health request succeeds. An old backend that omits live readiness conditions, or a live unknown condition, cannot satisfy default --wait on its own.
• 1ctl app status displays Application readiness: <state> (<basis>); JSON exposes the additive condition model at status.readiness. It separates reconciliation and generation, workload and replica counts, application state/basis, and Phase 3 route, dns, and public_reachability not_observed/unknown placeholders. The placeholders are not observed external route, DNS, or public-reachability state.
• A generated default hostname is an allocated reservation for the application, not proof that a public endpoint is ready. Where present, domain_status.dns.condition is the authoritative DNS result: only verified proves that the reserved hostname resolves to its expected target. pending, nxdomain, wrong_target, and error do not make DNS, the public route, or application readiness successful. Route and application readiness remain separate conditions.
• READINESS_UNVERIFIED means configure or repair the readiness signal and retry after inspecting status and logs. READINESS_FAILED means a reported reconciliation, workload, or application condition is failing; correct it, then retry.
• app delete reports cleanup results returned by the backend, including persistent-volume state.

Domain contract

• Production default-hostname configuration requires both DEFAULT_HOSTNAME_DOMAIN and DEFAULT_HOSTNAME_EXPECTED_TARGET; see the domain architecture reference for the operator contract. Non-production localhost defaults are not a production fallback.
• 1ctl domains add|list|remove|check|setup is the current custom-domain interface.
• domains check must distinguish backend attachment, route attachment, DNS, TLS, and optional HTTP reachability.
• Domain diagnostics should not report a detached domain as healthy.

Volume contract

• Persistent volumes are created through deploy volume flags or [volume] in satusky.toml.
• 1ctl volumes is the current inspection and lifecycle surface.
• Destroy operations must make PVC deletion state explicit.

Machine contract

• 1ctl machine resolves machine references from the authenticated user’s owned machines.
• Inventory create/update/delete operates through the authenticated machine API.
• machine inspect combines inventory, hardware, labels, and Talos status where available.
• machine available lists rentable capacity and supports resource filters.

Output contract

• --output json works before or after common subcommands.
• Commands intended for scripting should return structured JSON without requiring table parsing.
• Failed API operations exit nonzero. In JSON mode, failures preserve the backend’s safe diagnostics: error, code, message, details, retryable, remediation, and request_id when available.
• Use code and retryable for automation; retain request_id when contacting support. Older backend responses that provide only error and message remain readable during the compatibility window.