Compatibility
Language Runtimes
Section titled “Language Runtimes”| Area | Current target |
|---|---|
| TypeScript/Node packages | Node >=22 where package engines are declared. |
| Python packages | Python >=3.12. |
| Go modules | Go 1.26 where modules declare a version. |
| Root package manager | pnpm@11.1.1. |
Deployment Targets
Section titled “Deployment Targets”| Target | Source |
|---|---|
| Local development | caracal up and infra/docker/docker-compose.yml. |
| Self-hosted Compose | infra/docker/runtime-compose.yml with versioned GHCR images. |
| Kubernetes | infra/helm/caracal. |
| Docs site | Astro ^7.0.6 and Starlight 0.41.3. |
Release and Platform Targets
Section titled “Release and Platform Targets”- Release binaries target Linux x64/arm64, macOS x64/arm64, and Windows x64.
- Current Kubernetes operations guidance targets Kubernetes 1.30 or newer.
- Published modes are
rcandstable. They use the same fail-closed security posture;rcdenotes pre-release maturity, not relaxed security.
Version Pinning
Section titled “Version Pinning”Caracal packages release in lockstep: every @caracalai/* npm package, caracalai* Python distribution, and Go module tag carries the same version, and cross-package wire contracts are only validated within one release. Pin every Caracal package in a service to one exact version and upgrade them together - a mixed set (for example an older @caracalai/oauth under a newer @caracalai/sdk) is unsupported and can fail in ways that look like platform errors. Lockfiles make this the default; when bumping, change every Caracal entry in the same commit.
v0.2 Stability
Section titled “v0.2 Stability”Caracal is on a pre-1.0 SemVer line. Patch releases preserve documented public behavior while repairing defects. A minor release may change public APIs or operational contracts, so read its release notes and upgrade all Caracal artifacts together.
Compatibility promises cover documented package exports, public product APIs, and raw protocol fields identified as wire contracts. Internal storage names, internal endpoints, unpublished exports, and implementation details are not public compatibility guarantees. When a public surface is deprecated, its notice names the replacement and intended removal minor; pre-1.0 consumers must not assume a multi-major deprecation window.
This open-source compatibility policy does not imply a support SLA.
Next Step
Section titled “Next Step”Use Release Map to map product versions to packages, images, and release surfaces.