Carapace

Getting Started / Install

Install Carapace

Outcome

Install cara, optionally verify signatures/checksums, and confirm it runs.

1) Download a release binary

Use a direct download link for your platform (fastest path for most users):

Release page: https://github.com/puremachinery/carapace/releases/latest

Use releases/latest for quick interactive installs. For automation, reproducible rollouts, and explicit rollback control, use pinned tag URLs.

If you specifically need a preview build, pin the exact preview tag.

Quick path for first-time setup:

  1. Download your platform binary (above).
  2. Make it executable and move it onto your PATH (see "Install on your PATH" below).
  3. Run cara version to confirm.

If you want the shortest stable first-run path after install, plan to start with:

Use the Providers hub if you are deciding between Anthropic, OpenAI, Ollama, Gemini, Bedrock, or Venice. Use Help if you want guided setup help instead of choosing alone.

Signature and checksum verification (next two sections) are recommended, especially for production or automation.

VERSION="vX.Y.Z"
BASE_URL="https://github.com/puremachinery/carapace/releases/download/${VERSION}"
curl -LO "${BASE_URL}/cara-x86_64-linux"
$Version = "vX.Y.Z"
$BaseUrl = "https://github.com/puremachinery/carapace/releases/download/$Version"
Invoke-WebRequest "$BaseUrl/cara-x86_64-windows.exe" -OutFile ".\cara-x86_64-windows.exe"

Each release artifact has a matching .bundle file (Sigstore bundle). Compatibility .sig + .pem files are also published, but bundle verification is the primary documented path.

cara update uses the same bundle verification policy in-process and fails closed if authenticity checks fail.

Example for Linux x86_64:

curl -LO https://github.com/puremachinery/carapace/releases/latest/download/cara-x86_64-linux
curl -LO https://github.com/puremachinery/carapace/releases/latest/download/cara-x86_64-linux.bundle

cosign verify-blob \
  --bundle cara-x86_64-linux.bundle \
  --certificate-identity-regexp "https://github.com/puremachinery/carapace/.github/workflows/release.yml@refs/tags/v.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  cara-x86_64-linux

3) Verify checksum (optional)

Compute SHA-256 locally:

# macOS/Linux
shasum -a 256 cara-x86_64-linux
# Linux alternative
sha256sum cara-x86_64-linux
# Windows PowerShell
Get-FileHash .\cara-x86_64-windows.exe -Algorithm SHA256

For pinned releases, compare against release-provided checksums:

VERSION="vX.Y.Z"
BASE_URL="https://github.com/puremachinery/carapace/releases/download/${VERSION}"
curl -LO "${BASE_URL}/cara-x86_64-linux"
curl -LO "${BASE_URL}/SHA256SUMS.txt"
curl -LO "${BASE_URL}/SHA256SUMS.txt.bundle"

cosign verify-blob \
  --bundle SHA256SUMS.txt.bundle \
  --certificate-identity-regexp "https://github.com/puremachinery/carapace/.github/workflows/release.yml@refs/tags/v.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  SHA256SUMS.txt

grep "  cara-x86_64-linux$" SHA256SUMS.txt | sha256sum --check --strict

If you downloaded every artifact listed in SHA256SUMS.txt, you can also run:

sha256sum --check SHA256SUMS.txt

PowerShell example:

Prerequisite (Windows): Install cosign if needed (for example: winget install Sigstore.Cosign).

$Version = "vX.Y.Z"
$FileName = "cara-x86_64-windows.exe"
$BaseUrl = "https://github.com/puremachinery/carapace/releases/download/$Version"
$ErrorActionPreference = 'Stop'
Invoke-WebRequest "$BaseUrl/$FileName" -OutFile ".\$FileName"
Invoke-WebRequest "$BaseUrl/SHA256SUMS.txt" -OutFile ".\SHA256SUMS.txt"
Invoke-WebRequest "$BaseUrl/SHA256SUMS.txt.bundle" -OutFile ".\SHA256SUMS.txt.bundle"

cosign verify-blob `
  --bundle .\SHA256SUMS.txt.bundle `
  --certificate-identity-regexp "https://github.com/puremachinery/carapace/.github/workflows/release.yml@refs/tags/v.*" `
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" `
  .\SHA256SUMS.txt
if ($LASTEXITCODE -ne 0) {
  throw "cosign verification failed for SHA256SUMS.txt"
}

$expectedLine = (Select-String -Path .\SHA256SUMS.txt -SimpleMatch "  $FileName").Line
if (-not $expectedLine) {
  throw "No checksum entry found for $FileName in SHA256SUMS.txt"
}
$expected = ($expectedLine -split '\s+')[0].ToLower()
$actual = (Get-FileHash ".\$FileName" -Algorithm SHA256).Hash.ToLower()
if ($expected -ne $actual) {
  throw "Checksum mismatch for $FileName"
}
Write-Host "Checksum verified for $FileName"

Maintainer/operator shortcut for this full flow (run from the repo root):

./scripts/smoke/verify-release-artifacts.sh

4) Install on your PATH

macOS/Linux:

FILE="cara-<your-platform>"   # example: cara-aarch64-darwin
chmod +x "./${FILE}"
sudo mv "./${FILE}" /usr/local/bin/cara

Windows (PowerShell):

$installDir = "$env:LOCALAPPDATA\cara\bin"
New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Copy-Item .\cara-x86_64-windows.exe (Join-Path $installDir "cara.exe")

# Add to PATH for the current user (persistent across sessions)
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
$pathParts = if ($currentPath) { $currentPath -split ';' } else { @() }
if ($pathParts -notcontains $installDir) {
    $newPath = ($pathParts + $installDir) -join ';'
    [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
    $env:Path = if ($env:Path) { "$env:Path;$installDir" } else { $installDir }
}

If cara is not found in your current shell, restart your terminal.

5) Verify install

cara --help
cara version

Next step