---
title: Upgrading Sencho
description: How to update Sencho, what happens during upgrades, and the version policy.
---

<Note>
  Sencho is used in production for day-to-day Docker Compose and fleet management. As a pre-1.0 project it still evolves quickly, so review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and validate against your own setup before deploying it on critical infrastructure.
</Note>

## Upgrade steps

Upgrading Sencho is a two-command process. Pull the latest image and recreate the container:

```bash
docker compose pull
docker compose up -d
```

Or if you're running with `docker run`:

```bash
docker pull saelix/sencho:latest
docker stop sencho && docker rm sencho
# Re-run your original docker run command
```

<Tip>
  Sencho is also mirrored on GitHub Container Registry at `ghcr.io/studio-saelix/sencho:latest` with the same tags and digests as Docker Hub. Pull from whichever registry your environment prefers.
</Tip>

Sencho applies any necessary database migrations automatically on startup. No manual steps are required.

<Note>
  Remote nodes can be updated directly from the Fleet View without dropping to a shell. See [Remote Updates](/features/remote-updates) for details. Admiral **Hardened Build** installs use a different, entitlement-gated update path instead of the manual steps above; see [Updating the local (gateway) node](/features/remote-updates#updating-the-local-gateway-node) for that flow.
</Note>

---

## Automatic migrations

Sencho handles all schema changes internally. When the application starts, it checks whether the database needs updating and applies any pending migrations automatically. This covers:

- **New tables and columns** for features introduced in newer versions
- **Config import** from an on-disk JSON config file, if one exists from a manual setup
- **Admin account consolidation** into the multi-user system
- **Encryption of node API tokens** stored in plaintext (registry credentials are always stored encrypted, so they need no migration)
- **SSO and RBAC setup** for single sign-on provider config and role-based access
- **Obsolete column cleanup**, removing unused SSH/TLS configuration columns no longer read or written by the current schema
- **Blueprint rollout approval** columns (`approval_status`, intent fingerprint, and blast JSON). Existing Blueprints start **pending**. Automatic reconciliation and enforcement pause until an admin opens **Apply now**, reviews the rollout preview, and confirms. New installs behave the same way for each Blueprint until the first confirmation.

You never need to run SQL commands, migration scripts, or any manual database operations.

---

## Backup before upgrading

Always back up your data directory before upgrading. If something goes wrong, restoring from backup is the only recovery path. Sencho does not support downgrading or rolling back database migrations.

```bash
# Copy both the database and the encryption key
cp /path/to/sencho-data/sencho.db /path/to/backup/sencho-pre-upgrade.db
cp /path/to/sencho-data/encryption.key /path/to/backup/encryption-pre-upgrade.key
```

See the [Backup & Restore guide](/operations/backup) for full backup procedures.

---

## Pinning a specific version

If you prefer to control exactly which version you run, pin the image tag in your `docker-compose.yml`:

```yaml
image: saelix/sencho:0.96.0
```

Fleet can update semver pins directly from the [Node updates](/features/remote-updates) sheet: it rewrites the tag to the selected release before recreating the container. Digest pins and compose values that use variable interpolation must be changed manually before Fleet can update the node.

Check [GitHub Releases](https://github.com/studio-saelix/sencho/releases) for available versions and changelogs.

---

## Version policy

Sencho follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`):

| Change type | Version bump | Example |
|-------------|-------------|---------|
| Bug fixes, performance improvements | Patch | 0.38.0 → 0.38.1 |
| New features | Minor | 0.38.x → 0.39.0 |
| Breaking changes | Major | 0.x.y → 1.0.0 |

<Note>
  While the version is below 1.0, minor releases (0.x.0) may occasionally include breaking changes. These are always documented in the release notes. Once Sencho reaches 1.0, breaking changes will only occur in major releases.
</Note>

Breaking changes are marked with `BREAKING CHANGE` in the [release notes](https://github.com/studio-saelix/sencho/releases). Subscribe to the repository's releases to be notified of new versions.