Migration Guide

Migration Guide

This page documents breaking changes between COI versions and how to migrate. Check this page after a coi update if the release notes mention configuration or behavior changes.

Config File Location: .coi.toml → .coi/config.toml

In earlier versions of COI, the project config file was .coi.toml at the project root. This has been replaced by .coi/config.toml in a directory.

Before:

your-project/
├── .coi.toml       ← old location
└── ...

After:

your-project/
├── .coi/
│   └── config.toml ← new location
└── ...

Migration Steps

1. Create the .coi/ directory in your project root:

mkdir -p .coi

2. Move the old config file:

mv .coi.toml .coi/config.toml

3. Update your .gitignore if needed — the directory form is typically still excluded:

# If you were ignoring the old file, update to the directory
.coi/

4. Profile directories also move: ~/.coi-profiles/ → ~/.coi/profiles/ (user-level) and .coi-profiles/ → .coi/profiles/ (project-level). Move your profile directories accordingly.

COI will warn on startup if it detects a .coi.toml at the project root and no .coi/config.toml, so you will not silently lose configuration.

Mount Syntax: [[mounts]] vs [[mounts.default]]

The mount table key differs between the main config and profile configs:

Context	Correct key
~/.coi/config.toml or .coi/config.toml	[[mounts.default]]
.coi/profiles/NAME/config.toml	[[mounts]]

Main config:

# .coi/config.toml
[[mounts.default]]
host = "~/.claude/skills"
container = "/home/code/.claude/skills"
readonly = true

Profile config:

# .coi/profiles/rust-dev/config.toml
[[mounts]]
host = "~/.cargo"
container = "/home/code/.cargo"

Using [[mounts]] in the main config or [[mounts.default]] in a profile config will result in the mounts being silently ignored. If extra files are not appearing in the container, check the mount key.

Checking Your Current Version

coi version

Compare against the releases page to identify which migrations apply to your upgrade path.

---

See Also

• Configuration - Full configuration reference with all current options
• Profiles - Profile directory structure and config reference
• System Health Check - Verify your environment after migrating