> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tofunmiadewuyi.com/custos/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading the control plane

> Replace the custoscp binary, with or without database migrations, and roll back.

The control plane runs as `/usr/local/bin/custoscp` under systemd. Release notes
state whether a release includes database migrations. Use the matching procedure
below. For an ARM64 server, replace `amd64` with `arm64`.

## Upgrade without migrations

Download the latest binary, keep the installed binary as a quick rollback,
replace it, and restart the service:

```bash theme={null}
VERSION="$(curl -fsSL https://custosd.tofunmiadewuyi.com/releases/custoscp/latest.txt)"

curl -fL \
  -o /tmp/custoscp.tar.gz \
  "https://custosd.tofunmiadewuyi.com/releases/custoscp/${VERSION}/custos_${VERSION}_linux_amd64.tar.gz"

tar -xzf /tmp/custoscp.tar.gz -C /tmp

sudo cp /usr/local/bin/custoscp /usr/local/bin/custoscp.previous
sudo install -m 0755 /tmp/custos /usr/local/bin/custoscp
sudo systemctl restart custoscp
```

Verify it:

```bash theme={null}
custoscp version
systemctl status custoscp
curl http://127.0.0.1:8123/readyz
```

## Upgrade with migrations

Download the latest binary, stop the service, run the migrations embedded in
the new binary, install it, and start the service:

```bash theme={null}
VERSION="$(curl -fsSL https://custosd.tofunmiadewuyi.com/releases/custoscp/latest.txt)"

curl -fL \
  -o /tmp/custoscp.tar.gz \
  "https://custosd.tofunmiadewuyi.com/releases/custoscp/${VERSION}/custos_${VERSION}_linux_amd64.tar.gz"

tar -xzf /tmp/custoscp.tar.gz -C /tmp

sudo cp /usr/local/bin/custoscp /usr/local/bin/custoscp.previous
sudo systemctl stop custoscp

CUSTOS_DATABASE_URL="$(sudo systemd-creds decrypt /etc/credstore.encrypted/CUSTOS_DATABASE_URL -)" \
  /tmp/custos migrate up

sudo install -m 0755 /tmp/custos /usr/local/bin/custoscp
sudo systemctl start custoscp
```

Verify it with the same three commands shown above. If the migration command
fails, the new binary has not been installed; restart the existing service:

```bash theme={null}
sudo systemctl start custoscp
```

## Roll back the binary

```bash theme={null}
sudo install -m 0755 /usr/local/bin/custoscp.previous /usr/local/bin/custoscp
sudo systemctl restart custoscp
```

`custoscp.previous` is kept deliberately — do not clean it up. Each upgrade
overwrites it with the version you are replacing, so it never accumulates and is
always exactly one release behind. The daemon keeps `custosd.prev` the same way.

Rolling back the binary does not reverse a migration. Follow the release notes
if a migrated release needs to be rolled back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.