Upgrading Pi Agent: v0.13.0 API Key Migration Pitfalls

Why upgrading deserves a chapter of its own

Home Assistant add-ons are updated far more frequently than ordinary apps. Pi Agent went from 0.1.0 to 0.13.1 in about six months, with more than 20 releases along the way. Most contained behind-the-scenes fixes—nginx fixes related to Ingress or clearer log messages—and could be installed without further action. Every so often, however, a release breaks your existing configuration. This is known as a breaking change.

Pi Agent’s most noticeable breaking change so far arrived in v0.13.0. Previously, Home Assistant’s Add-on → Configuration tab displayed seven password fields, including “GLM API Key,” “OpenAI API Key,” and “Anthropic API Key.” After upgrading, the entire group disappears. The uncluttered screen can make it look as though the add-on is broken. The fields have simply moved to the pi-web Models panel described in Chapter 6, and you must enter the keys there manually.

This chapter gives you three practical skills:

• A consistent pre-upgrade routine—create a Home Assistant backup (as explained in Chapter 20) and copy your current keys to a password manager. Even if an upgrade fails, you can recover in about three minutes.
• The ability to read the CHANGELOG—if a release contains terms such as Breaking or Migration required, stop and read the entire entry before selecting Update.
• A downgrade strategy—Pi Agent has no one-click rollback button, so recovery depends on the backup you create before upgrading. This chapter explains how to restore it and what happens to your conversations.

Pi Agent version timeline: milestones to watch

If you installed Pi Agent today, you already have the latest version and can skim this section for background. If you have been upgrading from an older release, this timeline highlights the versions that require particular attention.

The story behind the v0.13.0 breaking change

This is the most important section in the chapter: it accounts for the problem encountered by 90% of people upgrading from an older release.

In v0.12.x and earlier: Open Home Assistant → Add-on → Pi Agent → Configuration, and you see a complete set of password fields:

api_key:              <GLM-key>
minimax_api_key:      <MiniMax-key>
openai_api_key:       <OpenAI-key>
openrouter_api_key:   <OpenRouter-key>
anthropic_api_key:    <Anthropic-key>
deepseek_api_key:     <DeepSeek-key>
groq_api_key:         <Groq-key>

You entered the keys there, selected Save, and restarted the add-on. At startup, pi-web wrote them to /data/pi-agent/models.json, enabling the chat page to work.

In v0.13.0 and later: All seven password fields are gone. The Configuration tab instead contains four container-level options:

Provider keys now belong in the pi-web Models panel. Select Models in the left-hand tab bar, choose “+ Add Provider,” and enter the base URL and key there.

Why such a large change? The official CHANGELOG gives a straightforward reason: two different interfaces used to write to /data/pi-agent/models.json—Home Assistant’s Configuration tab and the pi-web UI—and they could overwrite one another. If you added a new provider such as xAI Grok in pi-web, restarting the add-on caused the startup script to remove it because it was not on the Configuration tab’s allowlist. This refactor gives one interface sole responsibility for the file.

There is no automatic migration. The CHANGELOG explicitly says “no auto-migration; hard cut.” Upgrading does not copy your old keys into the Models panel. The old models.json file remains, but placeholders such as "$GLM_API_KEY" resolve to empty strings, so all requests return 401 until you re-enter the keys. This is the expected post-upgrade state, not a bug.

Complete procedure: upgrading from v0.12.x to v0.13.x

Follow these steps in order. Even if you are uncomfortable changing system settings, this procedure provides a safe path through the upgrade.

1. Create a Home Assistant backup before upgrading

   As explained in Chapter 20, go to Settings → System → Backups → Create backup in the Home Assistant sidebar. Choose a full backup, or at minimum include the Pi Agent add-on. Give it a recognizable name such as pre_pi_agent_0.13.0. Wait for the backup to finish—usually 1–3 minutes. This is your recovery point.

2. Copy every API key to a password manager

   Open Add-on → Pi Agent → Configuration. Reveal, copy, and save every populated *_api_key field in your password manager. The seven possible providers are GLM, OpenAI, Anthropic, DeepSeek, Groq, OpenRouter, and MiniMax; copy the keys for every provider you configured. This is your only way to recover those key values after the upgrade.

3. Return to the add-on page and select Update

   Open Add-on → Pi Agent → Info. The new version number and Update button appear at the top. Select Update; Supervisor downloads the new image and restarts the container. This usually takes 2–5 minutes, although downloading the image for the first time may take longer. A stream of messages on the Logs tab is normal during this process.

4. After the upgrade, check Logs for a successful startup

   A message such as pi-web listening on :30141 confirms that pi-web is running. Because the keys referenced by models.json are now empty, Logs may also contain 401 warnings. At this stage, those warnings are expected.

5. Open pi-web and re-enter each key in the Models panel

   Select Pi Agent in the Home Assistant sidebar, then open the Models tab on the left. For each provider, the API Key field will be empty or marked “Not set.” Select Edit and paste in the corresponding key from your password manager. Select Test; a green check mark confirms connectivity. Then select Save. Repeat for all seven providers you use. The detailed procedure is the same as in Chapter 6.

6. Verify the upgrade with a new conversation

   On the main chat screen, create a new session, select a provider, and send “Hello.” A normal response confirms that both the upgrade and key re-entry succeeded. Sessions created before the upgrade should still be present and can be continued normally.

7. Review the four new container options

   Return to Add-on → Configuration and review log_level, timezone, reset_video_tools, and env_vars. Most people only need to set timezone to their IANA time-zone identifier; for Taiwan, use Asia/Taipei. This aligns log timestamps and schedules with local time. Leave the other three settings at their defaults unless you have a specific need.

Standard post-upgrade checklist

Whether you install a major change such as v0.13.0 or a small patch such as v0.13.1, run this checklist immediately afterward. It takes three minutes and catches problems before you discover them in the middle of important work.

1. Is the Pi Agent button still in the Home Assistant sidebar?

   Refresh the Home Assistant page and confirm that Pi Agent, with its robot icon, still appears in the left sidebar. Since v0.8.0, startup automatically enables this button, so it should not normally disappear. If it is missing, see item 3 in the troubleshooting section below.

2. Are all providers present and passing tests in Models?

   Open Models from the left-hand tab bar. All 7 providers you previously configured should still be listed. Select Test for each one; the check is complete only when every configured provider shows green. A red cross usually indicates an invalid key or, more rarely, a provider base URL that has changed.

3. Are all historical conversations in the Sessions list?

   On the main chat screen, inspect the Sessions list in the sidebar. Every pre-upgrade conversation should still be listed and remain readable when opened. If any are missing, restore the backup immediately; see the downgrade section below.

4. Are all installed Skills present?

   Open Skills from the left-hand tab bar. Every Skill installed before the upgrade should still be listed. Since v0.12.0, the included git and openssh-client packages also make reinstalling a Skill reliable.

5. Can a new conversation receive a reply?

   Create a new session, choose a provider, and send “hello.” A reply within 3 seconds means everything is working. A 401 means the key is missing or invalid; a timeout suggests provider congestion at peak hours or a disconnected VPN; and a 404 usually means the model name is wrong, perhaps because the default model list changed.

How to downgrade

Pi Agent does not have a one-click rollback button. This is common to Home Assistant add-ons, not a flaw unique to Pi Agent. There are two ways to return to an earlier version: the standard method and an advanced alternative.

1. Standard method: restore the pre-upgrade backup

   In the Home Assistant sidebar, go to Settings → System → Backups and find the backup you created immediately before upgrading—the one from step 1 of the procedure. Select Restore, choose to restore only the Pi Agent add-on, and wait 3–5 minutes while Supervisor reinstalls the old image and restores the earlier /data/pi-agent/ directory. Pi Agent then returns completely to its pre-upgrade state, including its version, keys, Sessions, and Skills. This is why Chapter 20 emphasizes that a pre-upgrade backup is essential rather than optional.

2. Advanced method: install a specific version

   Open Add-on → Pi Agent → Info and use the three-dot menu in the upper-right corner. Its location varies slightly between Home Assistant versions, and some versions show it only after you enable Advanced Mode. If available, choose “Install a specific version” and enter an older version such as 0.12.0. Supervisor pulls that tag from GHCR and reinstalls it. However, your /data/pi-agent/ directory remains in the state written by the newer release, which may cause compatibility problems—for example, an older release may be unable to read the newer models.json schema. This method is only for experienced system administrators; everyone else should restore the pre-upgrade backup.

3. Will conversations created after the upgrade disappear?

   Yes. A backup is a time machine: restoring Pi Agent returns its data to the pre-upgrade moment. Sessions created, keys entered, and Skills installed after the upgrade all disappear. Before restoring, decide whether any new conversations matter. If they do, manually export their .jsonl files first—Chapter 8 explains where to find session files—then copy them back into /data/pi-agent/sessions/ after the restore.

4. After restoring, make sure automatic updates are off

   Otherwise, you could accidentally select Update again a few days later. Home Assistant has no official switch that pauses update notifications for one add-on, but you can disable Auto update on the add-on page if it was enabled. Make a note to remain on this version until the maintainer releases a version that resolves the breaking-change issue.

Common post-upgrade symptoms

If something seems wrong after an upgrade, compare the symptom with this table first. Most problems match one of these cases. If yours does not, continue to the troubleshooting section below.

How to read the release notes (CHANGELOG)

Every Pi Agent release records what changed, why it changed, and whether anything is breaking in the same CHANGELOG.md file on GitHub:

https://github.com/WOOWTECH/Woow_ha_pi_agent_add_on/blob/main/CHANGELOG.md

You do not need to know GitHub to read it. Open the URL in a browser: the latest release is at the top, with earlier releases listed below. Each version has a bulleted summary of its changes.

Watch for these keywords:

For example, the first item for v0.13.0 says, “BREAKING: AI provider API keys moved out of the addon Configuration tab into the pi-web UI.” The keyword is capitalized and appears at the start of the entry so that you will not miss it. The same entry says, “Migration: after upgrade, open pi-web and re-enter each key inside the Models panel,” which tells you exactly what to do.

Should you enable automatic updates?

The add-on Info page usually includes an Auto update switch. In newer Home Assistant versions it appears near the top of the page; in older versions, or when Advanced Mode is disabled, you may need to enable Advanced Mode in your user profile before it appears. When Auto update is on, Supervisor downloads and installs new releases without asking. For a rapidly evolving 0.x add-on such as Pi Agent, it is not recommended for three reasons:

Recommended cadence: Update manually. Check the add-on page once a week or on a free weekend. If a release is available, read the CHANGELOG before deciding whether to install it. If it is not urgent, wait a week for early reports. Upgrade promptly when the release fixes a bug that is actively blocking you.

Common problems during an upgrade

1. The add-on will not start after selecting Update, and Logs is full of errors

   Do not reinstall immediately. Open Logs and find the first “Error” or “Fatal” message; later messages are usually cascading failures. Common causes are: (a) Docker failed to pull the image because of a network problem or a temporary GHCR outage—wait 5 minutes, then restart; (b) the Configuration schema changed—for example, before v0.13.0, api_key: "xxx" was a string, and a malformed hand-edited options.json can fail schema validation; or (c) env_vars contains an invalid variable name, which cannot begin with a number or contain a hyphen, causing startup to stop during the set -e stage. The first error usually identifies the root cause.

2. The add-on page has no Update button

   There are two likely explanations: (a) you already have the latest release, in which case the page shows text such as Current version: 0.13.1 (latest); or (b) Supervisor has not refreshed the add-on repository index. Go to Settings → Add-on Store, open the three-dot menu, select Reload, wait 30 seconds, and check again. If neither applies, restart Home Assistant Supervisor from Settings → System → Restart Supervisor; this usually retrieves the new release.

3. The update appears stuck halfway through

   Do not restart Home Assistant. Let the operation finish. Because the Pi Agent image contains Chromium and ffmpeg, Docker may need 5–10 minutes for the first download, or as long as 15 minutes on a slower connection. If there is still no progress after 20 minutes, check Logs for an error. Restart Supervisor and begin again only if the process is genuinely stuck; the partial download will be discarded.

4. The keys have been re-entered, but requests still return 401

   Possible causes include: (a) an extra space or line break was copied with the key—copy it again without leading or trailing whitespace; (b) a key was entered under the wrong provider, such as a GLM key under OpenAI—keys are provider-specific; or (c) the default model name changed, and a variant such as gpt-4o is no longer available to your account. Open the Pi Agent session log; Chapter 8 explains how to find the .jsonl file. The detailed message generally identifies the provider and model returning 401 or 404. You can also consult the complete error-code reference in Chapter 22.

5. video-tools keeps running after the update, and chat is slow

   On the first startup after v0.11.0 or v0.13.0—if you triggered reset_video_tools during either upgrade—Pi Agent must download the 720 MB Chromium and virtual-environment bundle again. pi-web remains usable during this period, but video-pipeline features must wait for installation to finish. Search Logs for video-tools-init to follow progress. When installation completes, it creates the sentinel file /data/pi-agent/.video-tools-installed. On subsequent startups, finding that sentinel lets the service finish within 100 milliseconds. See Chapter 18 for details.

6. The watchdog keeps restarting the add-on

   Since v0.10.0, Supervisor’s watchdog has probed /api/home. If pi-web repeatedly returns 5xx responses or fails to respond, Supervisor restarts it on every watchdog cycle. The Logs tab repeatedly shows “Watchdog restart of add-on pi-agent.” This indicates a genuine pi-web startup problem, not an external network problem. As in item 1, find the first error. To stop an endless restart loop, manually stop the add-on from its Info page, then diagnose that first error.

Frequently asked questions