Most releases you just install. One you do not.

Pi Agent went from 0.1.0 to 0.13.1 in about six months, across more than twenty releases. Almost all were repairs you never had to think about: nginx behaving better behind Ingress, clearer log messages. Install, carry on.

Every so often, though, a release changes something you set up. That is a breaking change, and the biggest so far is v0.13.0.

Three habits carry you through any release, and this article is built around them. Back up and copy your keys before touching Update. Read the release notes for Breaking and Migration. Know the way back before you need it.

Seven password fields, moved without a forwarding address

Up to v0.12.x, Add-on → Pi Agent → Configuration showed seven password fields, one per provider: GLM, MiniMax, OpenAI, OpenRouter, Anthropic, DeepSeek and Groq. You pasted the keys there, selected Save, and restarted. At startup pi-web wrote them into /data/pi-agent/models.json, and chat worked.

From v0.13.0 the group is gone. Four container-level options sit there instead:

The keys now live in one place: the Models panel inside pi-web, the same screen you used in Part 3.

flowchart TD
  A["Configuration tab
seven password fields"] --> C["/data/pi-agent/models.json"]
  B["Models panel in pi-web"] --> C
  C --> D["Two writers, one file.
A provider added in pi-web could be
removed on the next restart."]
  D --> E["v0.13.0 stops the Configuration tab
writing this file at all"]
  E --> F["One writer, no overwriting — and
no path for your old keys to travel"]

There is no automatic migration. The CHANGELOG does not soften it: no auto-migration; hard cut. Your old models.json is still on disk, but the placeholders inside it — "$GLM_API_KEY" and its six siblings — now resolve to empty strings. Every request returns 401 until you enter the keys again. That is the expected state, not a fault.

The Configuration tab, before the upgradeThe seven key fields v0.13.0 removes. Reach it from Add-on → Pi Agent → Configuration.

• Seven fields, one per provider — api_key, minimax_api_key, openai_api_key, openrouter_api_key, anthropic_api_key, deepseek_api_key, groq_api_key. This is the group that disappears.
• The eye icon at the right of each row uncovers a stored value. That is how you copy a key out before you upgrade, and it is the step nothing substitutes for.
• Four are filled, three are empty here, which is normal — you only fill in the providers you actually use. Copy the filled ones; there is nothing to copy from the rest.

Upgrading from v0.12.x to v0.13.x, in order

1. Step 1

   Create a Home Assistant backup

   Go to Settings → System → Backups → Create backup. Choose a full backup, or at minimum include the Pi Agent add-on. Name it something you will recognize later, such as pre_pi_agent_0.13.0. Usually 1-3 minutes, and it is your recovery point.

2. Step 2

   Copy every API key into a password manager

   Open Add-on → Pi Agent → Configuration. Reveal and copy every *_api_key field that has a value in it. After the upgrade, this is your only way back to those values.

3. Step 3

   Select Update on the Info page

   Open Add-on → Pi Agent → Info. The new version number and the Update button are at the top. Supervisor downloads the new image and restarts the container, usually in 2-5 minutes. A stream of messages on the Log tab is normal.

4. Step 4

   Check the log for a clean start

   A line reading pi-web listening on :30141 means pi-web is running. You will probably also see 401 warnings, because the keys are now empty. At this exact moment those warnings are correct.

5. Step 5

   Re-enter each key in the Models panel

   Open Pi Agent from the sidebar, then the Models tab. Each provider's API Key field will be empty or marked “Not set.” Select Edit, paste the key, select Test, wait for the green check, then Save. Repeat for every provider you use.

6. Step 6

   Send one message to prove it

   Start a new session, pick a provider, and send “Hello.” A normal reply means both halves worked — upgrade and keys. Sessions from before should still be in the list.

7. Step 7

   Set your time zone while you are here

   Back on Add-on → Configuration, set timezone to your IANA identifier — for Taiwan, Asia/Taipei. It lines log timestamps up with your clock. Leave the other three alone.

Step 3 starts hereThe Info page on 0.12.0 — the version this migration starts from.

• Current version: 0.12.0 sits under the title and tells you which side of the migration you are on. On 0.12.0, as here, the seven key fields are still waiting on the Configuration tab.
• Changelog is a link, right beside the version number. It opens the file the last section of this article asks you to read.
• Autoupdate is the third of the four toggles, and it is off in this screenshot. Leave it that way; the last section explains why.

Five things to look at after any upgrade

Run this after every release, breaking or not. It catches problems now rather than in the middle of something that matters.

• The sidebar button. Refresh Home Assistant. Pi Agent should still be in the left sidebar.
• The providers. Open Models. Every provider you configured should still be listed, and Test should go green on each. A red cross usually means an invalid key.
• Your conversations. Check the Sessions list. Old conversations should be there and should still open. If any are missing, restore the backup.
• Your Skills. Open Skills. Everything installed before should still be listed.
• One new message. New session, pick a provider, say hello. A reply within about three seconds is the test.

If that last one fails, the error code points the way: 401 means the key is missing or wrong, a timeout suggests provider congestion or a dropped VPN, and 404 usually means a model name that no longer exists.

Otherwise, match the symptom to the release behind it:

There is no rollback button, so there is a backup

Pi Agent has no one-click revert — true of Home Assistant add-ons generally, not a gap in this one. It leaves two routes back.

The standard route: restore the backup

Go to Settings → System → Backups and find the one from step 1. Select Restore, choose to restore only the Pi Agent add-on, and wait 3-5 minutes while Supervisor reinstalls the old image and puts back the earlier /data/pi-agent/. You land where you were: version, keys, Sessions, Skills.

The advanced route, and why it is second

The three-dot menu on the Info page may offer Install a specific version, where you name an older tag such as 0.12.0. Some Home Assistant versions show it only with Advanced Mode on. The catch: your /data/pi-agent/ stays as the newer release left it, and an older release may not read the newer models.json schema. If in doubt, restore the backup.

Whichever route you take, check Autoupdate is off before you walk away. Otherwise you do all of this again by accident in a few days.

Three minutes of reading, once a month

Every release records what changed, and whether anything breaks, in one file on GitHub:

You do not need to know GitHub to read it. Open the address; the newest release sits at the top. You are scanning for five words:

The v0.13.0 entry shows how readable this is. Its first line: “BREAKING: AI provider API keys moved out of the addon Configuration tab into the pi-web UI.” Further down: “Migration: after upgrade, open pi-web and re-enter each key inside the Models panel.” Most of this article is in those two sentences.

flowchart TD
  A["A new release appears"] --> B{"Does the entry say
BREAKING or Migration?"}
  B -->|"yes"| C["Back up, copy your keys,
read the whole entry"]
  B -->|"no"| D{"Does it fix something
that is blocking you?"}
  C --> E["Install it, then run
the three-minute check"]
  D -->|"yes"| E
  D -->|"no"| F["Wait a week; let early adopters
find the rough edges"]

For a 0.x add-on moving this fast, leave Autoupdate off. Three reasons:

• It skips your backup. Supervisor installs as soon as it sees a release. It never pauses to remind you to make a recovery point.
• It cannot do a migration. Nothing automated copies your keys into the Models panel. You meet the change as a screen full of 401s one morning, days after it happened.
• Fresh releases have rough edges. Waiting a week lets others find them and the maintainer publish an x.y.1 — as v0.13.1 did for the 413 upload problem.

Instead, look at the add-on page once a week, or on a free weekend. About once a month you will install what has piled up; make the backup the same day and the two become one habit. If you look after Home Assistant in two houses, upgrade them a week apart, so a bad release still leaves you one working system.

Where to go from here