Platform support

Use this page to understand where ota is first-class today and where the behavior is narrower.

This is the page that tells you what to expect before you assume a repo will behave the same everywhere.

• Linux is the strongest supported target
• macOS is also first-class
• Windows is supported, but with narrower shell and portability guarantees
• the support boundary matters most when a task body, healthcheck, or service command depends on shell syntax

Compatibility is about whether the declared contract and the current runtime match well enough to trust the result.

• a repo can be valid without being fully portable everywhere
• a command can be supported on a platform without behaving identically to every other platform
• ota should call out when behavior is narrower instead of pretending it is universal
• the contract should tell you what will work before you run it

• Linux: first-class target
• macOS: first-class target
• Windows: supported, but not identical to Unix-like shells

• use Linux or macOS when you want the smoothest default path
• use Windows when the repo contract explicitly handles its shell differences
• split tasks into variants when one shell syntax cannot cover every platform cleanly
• expect ota to warn when the declared behavior is narrower than the platform implies

• explicit platform declarations in the contract
• task variants when different shells need different bodies
• backend selection when the repo needs native, container, or remote execution
• supported shell syntax for the declared platform
• healthchecks and service commands that fit the current shell model

• shell syntax that only works on a different platform than the one declared
• contract fields that imply portability ota does not actually provide
• service or task commands that assume Bash-only behavior on Windows
• hidden fallback behavior that would make the runtime look more capable than it is

• Unix-like systems use sh -lc
• Windows uses cmd /C
• there is no per-task shell selection in V1
• if the command body assumes Bash behavior, that assumption must be explicit in the task or service design

Lifecycle tells you how ota treats execution reuse and isolation, not whether a repo is logically ready.

• persistent reuses a named container when container execution is configured
• ephemeral uses a fresh container when container execution is configured
• ephemeral means fresh for this invocation, not reused
• --native, --container, and --remote are backend shorthands for the mode-bearing repo commands, including ota run, ota up, ota doctor, and ota receipt
• ota run --ephemeral still provisions only the missing or mismatched contract requirements in that fresh container; it does not reinstall everything from scratch
• --ephemeral is the shorthand for --lifecycle ephemeral on ota run, ota up, ota doctor, and ota receipt
• --persistent is the shorthand for --lifecycle persistent on ota run, ota up, ota doctor, and ota receipt
• use ota clean when a container-backed task left stale runtime state behind; ota removes current and drifted repo-owned persistent containers plus dependency-isolation volumes
• outside backend-backed task execution, lifecycle is advisory
• ota does not create isolated temporary environments or automatic cleanup flows for ephemeral in V1

• expect the best behavior today on Linux and macOS
• expect Windows to work, but with more explicit shell syntax and fewer portability assumptions
• expect support warnings when the contract uses behavior the current platform cannot honor cleanly
• use task variants when one task name needs different bodies on different platforms
• treat shell behavior as part of the contract, not an invisible compatibility layer
• treat support policy as a boundary, not as a promise that every command will behave the same everywhere

• a repo has Windows users but shell bodies were written for Unix syntax
• a task works locally but fails in CI because the runner shell differs
• a service healthcheck uses shell features the current platform does not support
• a maintainer needs to decide whether to split a task into variants

• not a promise of identical shell behavior on every OS
• not per-task shell selection
• not automatic shell portability translation
• not isolated ephemeral workspace creation in V1
• not a guarantee that any shell snippet copied between platforms will work unchanged

• contract defines the repo’s execution intent
• shell-semantics defines the actual command invocation model
• doctor should explain support and compatibility failures clearly and early
• run and up should honor the platform boundary instead of hiding it
• support policy tells you what platform boundaries ota expects you to respect