Migrating from Manual Configs

Why migrate?

Manual configs drift.

If you use more than one provider, you end up repeating the same work in multiple formats:

MCP server definitions
permissions / approval settings
long-form instructions
skill references

AgentStack’s current answer is:

one canonical profile
one local hub runtime
provider-native materialization when needed

Step 1 — Capture your current setup

If you already use one provider, import it:

agentstack import \
  --from codex \
  --source ~/.codex/config.toml \
  --profile-file ~/.agentstack/profiles/main/agentstack.yaml

Or start interactively:

agentstack init --profile main

Step 2 — Review the canonical profile

Open the generated profile and check:

enabled providers
instructions
MCP servers
skills
provider overrides

Current v3 lives at:

~/.agentstack/profiles/main/agentstack.yaml

Step 3 — Activate the hub runtime

agentstack profile activate main

This switches active-profile, generates hub SKILL.md files, and wires supported tool skill directories.

Step 4 — Run doctor

agentstack doctor \
  --profile-file ~/.agentstack/profiles/main/agentstack.yaml

Step 5 — Materialize the providers you actually use

agentstack apply \
  --profile-file ~/.agentstack/profiles/main/agentstack.yaml \
  --to claude

agentstack apply \
  --profile-file ~/.agentstack/profiles/main/agentstack.yaml \
  --to opencode

Step 6 — Normalize your workflow

Once you migrate, stop editing every provider config by hand.

Instead:

update the AgentStack profile
activate if hub behavior changed
apply to the providers you want to use

Step 7 — Move toward package-first profiles

The current v3 model still centers on one manifest, but the direction is to keep each profile as a package/repo with instructions, skills, MCP wrappers, env examples, and docs next to the manifest.

See Profile Packages for that direction.