Platform Support
August 9, 2026 · View on GitHub
Operating system and runtime backend compatibility for Ouroboros.
For installation instructions, see Getting Started.
Requirements
- Python: >= 3.12 for core and non-LiteLLM profiles
- Package manager: uv (recommended) or pip
Operating System Support Matrix
| Platform | Status | Notes |
|---|---|---|
| macOS (ARM/Intel) | Supported | Primary development and CI platform |
| Linux (x86_64) | Supported | Tested on Ubuntu 22.04+, Debian 12+, Fedora 38+ |
| Linux (ARM64) | Supported | Tested on Ubuntu 22.04+ (aarch64) |
| Windows (WSL 2) | Supported | Recommended Windows path; runs the Linux build |
| Windows (native) | Experimental | See Windows caveats below |
Runtime Backend Support Matrix
| Runtime Backend | macOS | Linux | Windows (WSL 2) | Windows (native) |
|---|---|---|---|---|
| Claude Code | Yes | Yes | Yes | Experimental |
| Codex CLI | Yes | Yes | Yes | Not supported |
| (custom adapter) | Depends on adapter | Depends on adapter | Depends on adapter | Depends on adapter |
See the runtime capability matrix for a feature comparison across backends.
Linux Distribution Notes
- Ubuntu/Debian: Python 3.12+ may require the
deadsnakesPPA on older releases. - Fedora 38+: Python 3.12 is available in the default repositories.
- Alpine: Not tested. Native dependencies may require additional build tools.
Windows (WSL 2)
For the best Windows experience, use WSL 2 with a supported Linux distribution (Ubuntu recommended). All runtime backends and features are fully supported under WSL 2.
Windows 11 Home is a valid WSL 2 host when virtualization and the required Windows optional features are available. If WSL itself will not install, follow the Windows WSL 2 troubleshooting guide before installing Ouroboros.
Windows (native) Caveats
Native Windows support is experimental. Known limitations:
- File path handling: Some workflow operations assume POSIX-style paths.
- Process management: Subprocess spawning and signal handling differ on Windows.
- Codex CLI: Not supported on native Windows. Use WSL 2 instead.
- Terminal/TUI: Requires a terminal with ANSI support (Windows Terminal recommended;
cmd.exeis not supported). - CI testing: Native Windows is not part of the current CI matrix.
If you encounter Windows-specific issues, please open an issue with the platform:windows label.
Python Version Compatibility
| Python Version | Status |
|---|---|
| 3.12 | Supported |
| 3.13 | Supported |
| 3.14 | Supported for core and non-LiteLLM profiles |
| 3.14 beta/RC | Best effort |
| < 3.12 | Not supported |
The minimum required version is Python >= 3.12 as specified in pyproject.toml. Source checkouts default to stable Python 3.14 through .python-version; that default does not narrow the supported runtime range to 3.14-only.
Python Profile Matrix
| Profile | Supported Python | Python 3.14 behavior |
|---|---|---|
| Base package | 3.12-3.14 | Install and run |
claude, claude-cli, claude-sdk, mcp, tui, and supported non-LiteLLM combinations | 3.12-3.14 | Install and run |
litellm | 3.12-3.13 | Package installs, but the LiteLLM dependency is omitted by its Python marker |
all | 3.12-3.13 for LiteLLM; 3.12-3.14 for remaining extras | Installer selects Python 3.13 when available; direct 3.14 installs omit LiteLLM |
Source checkout with --extra all | 3.12-3.13 for LiteLLM; 3.14 for remaining extras | Select Python 3.13 for the co-installable profile; Python 3.14 omits LiteLLM |
LiteLLM currently publishes a <3.14 Python bound. Use Python 3.13 for current LiteLLM examples, or Python 3.12 when validating the lower supported bound. On Python 3.14, the public extras remain installable but omit LiteLLM; requesting the LiteLLM backend then returns remediation for creating a Python 3.13 environment.
MCP 2 and Claude Package Profiles
The package profile is a process contract, not a dependency-pin workaround:
| Extra | Transport/runtime | Python payload | Combine with [mcp]? |
|---|---|---|---|
[claude] | Default in-process Claude Agent SDK runtime | Exact SDK/Anthropic pins and MCP 1.x graph | No — separate process/environment |
[claude-cli] | Claude CLI subprocess for completions and agent workers | None | Yes |
[mcp] | MCP 2 server/client process | mcp==2.0.0 | Yes, with CLI profiles |
[claude-sdk] | Explicit alias for the Claude Agent SDK runtime | Same exact SDK/Anthropic pins and MCP 1.x graph | No — separate process/environment |
[all] | MCP 1.x application bundle | Includes [claude]; excludes MCP 2 | No — run [mcp] separately |
Supported resolver commands include:
uv tool install 'ouroboros-ai[claude]'
uv tool install 'ouroboros-ai[mcp,claude-cli]'
uv tool install 'ouroboros-ai[claude-sdk]'
ouroboros-ai[mcp,claude], [mcp,claude-sdk], and [all,mcp] are unsupported.
A normal resolver rejects their MCP 2/MCP 1.x constraints. If an environment is
forced past dependency resolution, setup and ouroboros mcp doctor fail before
changing configuration with this message:
Unsupported package profiles: ouroboros-ai[mcp] requires MCP 2, while ouroboros-ai[claude] and ouroboros-ai[claude-sdk] require MCP 1.x. Use [claude] alone for the Claude SDK runtime, or use [claude-cli] with [mcp]; run the MCP 2 server in a separate environment/process.
Migration from 0.50.8 and earlier
| Previous command/state | New action | Result |
|---|---|---|
[claude] or runtime_backend: claude | Keep [claude]; run ouroboros setup --runtime claude | Preserves SDK hooks/streaming on MCP 1.x |
Explicit CLI worker (runtime_backend: claude_mcp) | Install [claude-cli]; run ouroboros setup --runtime claude-cli | Preserves the out-of-process worker used by MCP 2 |
[claude-sdk] | Keep the profile or use [claude]; both select the SDK runtime | Makes the alias explicit without changing behavior |
[mcp,claude] silently resolved to 0.50.6 | Replace it with two environments: [claude] for the app and [mcp] for the server launcher | Prevents backtracking and preserves both MCP majors |
[all] application bundle | Keep [all] alone; launch [mcp] through isolated uvx/pipx | Prevents an implicit MCP-major collision |