Upgrading

Channels

Carabase release tags follow semver-prerelease conventions:

Channel	Tag pattern	Audience
`stable`	`v0.1.0`, `v0.2.0`	Public default. Use this unless you have a reason not to.
`beta`	`v0.1.0-beta.N`, `v0.1.0-rc.N`	Invited testers. RCs ride the beta channel — they’re the user-visible signal we’re stabilizing toward a release.
`alpha`	`v0.1.0-alpha.N`	Internal dogfood. May break, may be reverted.

The channel for any given build is derivable from the version string — no separate config needed. GET /api/v1/version reports channel directly.

Switching channels

# As a workspace setting
curl -X PUT http://localhost:3000/api/v1/workspace-settings \
  -H "x-workspace-id: $WORKSPACE_ID" \
  -d '{ "update_channel": "beta" }'

The Admin SPA’s Workspace page will surface this as a dropdown once the in-app updater UI ships.

Checking for updates

GET /api/v1/updates (coming) returns the latest tag in your subscribed channel from the GitHub Releases API:

{
  "current_version": "0.1.0",
  "latest_version": "0.1.1",
  "channel": "stable",
  "update_available": true,
  "release_notes_url": "https://github.com/carabase/carabase-host/releases/tag/v0.1.1",
  "published_at": "2026-04-25T10:00:00Z"
}

The host polls GitHub at most once per 24 hours, with ETag caching, and only PULLs — no telemetry is sent in either direction.

You can opt out via the update_check_enabled workspace setting. On by default.

Applying an update

The host doesn’t auto-apply. The pnpm deploy:prod flow is the canonical path:

# Pin to a specific tag
pnpm deploy:prod --tag v0.1.1

# Or follow main (default)
pnpm deploy:prod

See Production deployment for the full deploy sequence — backup, migrate, build, restart, smoke, auto-rollback on failure.

Rolling back

pnpm rollback:prod --to v0.1.0

Rollback doesn’t re-run migrations. If a release ships a forward-incompatible migration, restore from the pre-deploy backup instead.

What’s still on the roadmap for v0.1

The in-process update-checker service that polls GitHub Releases
The Admin SPA banner that surfaces “update available”
A CLI pnpm carabase doctor command that shows version + setup status + update availability in one report
Channel-aliased Docker tags (ghcr.io/carabase/carabase-host:alpha)
SBOM (CycloneDX) attached to every release
cosign signing of release artifacts

Track progress via the w5 label on GitHub issues.