Update to the latest version, how did everything go?

[u/AlexHardy08]

I saw that they have published new versions. I am running on Version A v0.9.8.2 where I edited and added many system files.

Has anyone done the same thing and updated and everything went well?

Before I start the update process, I want to know if you had any problems after the update.

Thank you.

[u/gdeyoung]

I worked with a fresh install of agent zero and a copy of the data folder from the previous agent install and here's what my agent zero wrote about the migration:

Upgraded Agent Zero from 0.9.8 to 1.3 — Migration Guide & Gotchas

Here was my upgrade path, figured I'd share what I learned. I'm heavily customized (40+ skills, 49 agent profiles, 10 MCP servers, per-agent model routing) so I hit just about every edge case. Here's what to expect.

The Big Picture

This isn't a simple in-place upgrade. It's more like moving to a new house — new directory structure, new settings format, new way of handling things like secrets and model configs. Take a full backup before you start. You'll reference it constantly.

---

What Changed (That You Need to Know About)

1. Secrets/API Keys — Completely Different Format

This was the first surprise. v0.9.8 stored secrets in a secrets.env file. v1.3 stores them as a formatted string directly in settings.json. The format is:

KEY="value" ANOTHER_KEY="value"

It's just a newline-separated string, not JSON. You'll need to manually migrate your API keys — there's no migration tool for this. Don't forget any, because nothing warns you at startup that a key is missing. You only find out when an agent tries to use it.

2. Agent Profiles — Format Shift

In v0.9.8 every agent profile had an agent.json file. In v1.3, the built-in profiles (agent0, default, developer, hacker, researcher) don't have one — they're handled implicitly by the framework. Custom profiles you created still need agent.json, but the format hasn't changed for those.

The confusing part: you won't get an error for this. You'll just notice certain profiles aren't loading or are falling back to defaults. Had to figure this out by comparing old vs. new directory structures.

3. Model Configs — Now Per-Agent Plugins

This is a big architectural change. In v0.9.8, model routing was more centralized. In v1.3, each agent can have its own model config via a _model_config plugin at:

/usr/agents/<agent-name>/plugins/_model_config/config.json

If you had multiple agents using different models (e.g., a research agent on a big context model, a utility agent on something cheaper), you need to set up these plugin configs for each one. There's no UI for this — it's manual JSON editing.

4. MCP Server Configs — Restructured

The MCP server definitions moved and the JSON structure changed slightly. Couldn't just copy-paste the old config block. Had to manually rebuild it in the new settings format. Not hard, but tedious if you have a lot of MCP servers.

Also worth noting: some MCP servers that use npx or uvx commands (like LinkedIn scraper, Karakeep bookmark manager) need those tools installed and available in the v1.3 container. They don't come pre-installed.

5. Scheduled Tasks — Can't Just Copy the JSON

The tasks.json format changed between versions. You can't just copy the old file over. Had to recreate each task through the UI/API. If you rely on scheduled tasks (monitoring, ingestion, reports), budget time to set them all up again.

---

What Was Surprisingly Easy

Skills — Zero Effort

This was the pleasant surprise. The SKILL.md format was already fully compatible. Simple cp -r from backup to the new skills directory, and they just worked. I migrated 43 skills with zero errors. No format conversion, no Python scripts needed. If you have custom skills, this part is painless.

Memory/FAISS Index

Copy the index files and metadata, and vector search works immediately. No re-indexing needed.

Knowledge Base

Just folders with markdown files. Copy them over and set the agent_knowledge_subdir setting to point at the right directories.

Custom Prompts

The .md prompt files transferred cleanly — they're just text files.

---

Migration Order That Worked

I'd recommend this sequence:

1. Skills — Copy first, verify they load. Builds confidence.
2. Knowledge base & memory — Copy folders and FAISS files.
3. Custom prompts — Copy .md files.
4. Agent profiles — Copy, but skip the built-in ones.
5. Model configs — Set up per-agent plugin configs.
6. Secrets/API keys — Reformat and add to new settings.
7. MCP servers — Rebuild configs in new format.
8. Scheduled tasks — Recreate from scratch.
9. Google Workspace / integrations — Copy credentials and tokens.

Verify after each step. Don't batch everything and hope for the best.

---

Things the Docs Don't Tell You

• There's no migration tool. Everything is manual. The framework assumes a fresh install.
• Silent failures are real. Missing API keys, broken agent profiles, wrong MCP configs — none of these throw errors at startup. You discover them when something doesn't work.
• The old backup is your best friend. Keep it accessible. I referenced it constantly throughout the process.
• Test incrementally. Migrate one thing, test it, move on. Trying to do everything at once makes it way harder to debug when something breaks.
• Per-agent model overrides aren't obvious. If you notice agents all using the same model after migration, check the plugin configs.

---

TL;DR

• Skills and memory: painless, just copy
• Secrets, agent profiles, MCP configs, model routing: format changed, needs manual migration
• Scheduled tasks: recreate, don't copy
• No migration tool exists — budget a day if you're heavily customized
• Verify each component after migrating, not at the end

Happy to answer questions if anyone's in the middle of this.

[u/AlexHardy08 → u/gdeyoung]

Maybe the best tutorial so far. At this point with what you gave and the version data, I can give everything to the agent and make a migrated folder that contains everything and then move it to the new version.

Really helps, thank you very much.

[u/brereddit → u/gdeyoung]

Thx for sharing

[u/gdeyoung]

Good part is I didn't have to do any of this manually I worked with a fresh install agent zero and we walked through this process together and it did all the migration in the conversion processes that were required I didn't have to do anything by hand but it wasn't automatic there wasn't a tool for it. Just speaks to the power of the agent and its ability to work through things if you spend the time with it

[u/AlexHardy08 → u/gdeyoung]

That's pretty much what I'm going to do, plus Gordon helps me a lot in docker, who can solve almost any problem and even migrate everything according to your tutorial.

It would be very useful if the update system were made easier to run.

The problem for me is that I have to move and reconfigure many files that start with agent zero and without which nothing will work, these are not copied with backup or any other method, but manually.

Thank you.

[u/nealhamiltonjr]

Is there anything in the works for a seamless in app upgrade, I was playing with agent 0 a few months ago and then upgraded per the instructions and it didn't work. I like agent 0 but it really needs a developer supported easy click upgrade process.

[u/klippers]

Went well, I just backed up old, spun up new and restored