Step-by-step guide for upgrading an ɳSelf v0.9.x project to v1.0.9.

• Before you start
• Step 1: Upgrade the CLI
• Step 2: Run the migration
• Step 3: Re-install plugins
• Step 4: Verify the stack
• Command changes
• Environment file changes
• Plugin changes
• Troubleshooting
• Rollback

What changed in v1.0.0:

• The CLI was rewritten from Bash to Go. It is now a single binary.
• Plugin format changed from shell scripts to signed Go bundles. All v0.9 plugins must be re-installed.
• The environment file layout changed from a single .env to a cascade: .env.dev → .env.local → .env.staging/.env.prod → .env.secrets → .env.computed.
• The nginx config moved from nginx/ (flat) to nginx/sites/ (structured).
• .nself/config changed from a plain file to a directory.
• nself.sh (the v0.9 bootstrap script) is no longer used.

What nself migrate does automatically:

1. Stops running containers.
2. Backs up your current project state to .nself/backup/{timestamp}/.
3. Moves nginx configs to nginx/sites/.
4. Regenerates docker-compose.yml, nginx, and SSL certificates for v1.

What you must do manually after migration:

• Re-enter your license key: nself license set <key>.
• Re-install each plugin: nself plugin install <name>.

brew upgrade nself-org/nself/nself
nself --version
# Expected: nself v1.0.9 (darwin/arm64)

curl -fsSL https://install.nself.org | bash
nself --version

nself --version
# Must show: nself v1.0.9 or later

Navigate to your v0.9 project directory and run:

cd ~/my-nself-project

# First, scan to see what will be migrated
nself migrate detect

# Example output:
# Found 3 v0.9 artifact(s):
#   docker-compose.yml — v1-generated compose file
#   .env              — v1 environment file (NSELF_VERSION=0.x)
#   nginx/            — v1 nginx directory structure (missing nginx/sites/)
# Run: nself migrate run

# Run the full migration
nself migrate run

The migration is idempotent: running it on an already-migrated project exits cleanly with no changes.

Verify the migration completed:

# Should show: No v1 artifacts detected. This project is ready for nSelf v2.
nself migrate detect

# Check backup was created
ls .nself/backup/

Plugin signatures changed in v1.0.0. Every v0.9 plugin must be re-installed.

# Re-enter your license key
nself license set nself_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Re-install plugins (example — use your actual plugin list)
nself plugin install ai mux claw voice browser google notify cron

# Verify plugins are installed
nself plugin list

To find your original plugin list, check the v0.9 .env backup:

grep "PLUGIN_\|NSELF_PLUGIN" .nself/backup/*/  .env 2>/dev/null | grep "=true"

# Build the v1 configuration
nself build

# Start the stack
nself start

# Run diagnostics
nself doctor

Commands that changed from v0.9 to v1.0.9:

v0.9: Single .env file with all configuration including secrets.

v1.0.9: Cascade of env files, each for a specific purpose:

.env.dev        ← Team-shared defaults (tracked in git)
.env.local      ← Your machine-specific overrides (gitignored)
.env.staging    ← Staging overrides (tracked)
.env.prod       ← Production overrides (tracked, no real secrets)
.env.secrets    ← Real secrets — API keys, passwords (gitignored)
.env.computed   ← Generated by nself build (never edit manually)

Migration handles this automatically. After running nself migrate run, your old .env is backed up and nself build generates a compatible v1 configuration.

v0.9 env variables that changed:

All v0.9 plugins used shell scripts. v1.0.9 uses signed Go bundles. Plugins are incompatible across versions.

Plugin names that changed:

After migration, the CLI prints a warning showing which plugins were enabled in v0.9 and the exact commands to re-install them.

Error: Docker 24 or later is required (found: 20.10.x)

Upgrade Docker:

# macOS
brew upgrade docker

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install docker-ce

Error: port 5432 is already in use by process: postgresql (pid 1234)

Stop the conflicting service:

# macOS: stop local postgres
brew services stop postgresql

# Linux: stop local postgres
sudo systemctl stop postgresql

Your license key format is valid but the key must be re-entered after migration because the v0.9 key storage location changed:

# Re-enter the key explicitly
nself license set nself_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Verify acceptance
nself license info

v0.9 plugin names used the nself- prefix; v1.0.9 uses short names:

# v0.9 (wrong)
nself plugin install nself-ai

# v1.0.9 (correct)
nself plugin install ai

See the plugin name table above for the full mapping.

If nself migrate run fails partway through:

# Check what was backed up
nself migrate rollback --list

# Restore the last backup
nself migrate rollback

The rollback restores all files that were backed up before the failure.

Run with --full to get detailed diagnostics:

nself doctor --full

# Check for v0.9 global artifacts (stale paths)
nself doctor --check-legacy

If you need to revert to v0.9 after migrating:

# List available backups
nself migrate rollback --list

# Restore the most recent backup
nself migrate rollback

# Or restore a specific backup by timestamp
nself migrate rollback --backup 20260420-143022

After rollback, reinstall the v0.9 CLI (use the Homebrew formula version pin or download from GitHub releases).

The migration path is covered by a CI fixture that runs on every PR: see cli/internal/migration/testdata/v0.9-fixture/ and .github/workflows/migration-fixture.yml. The fixture plants all 5 v0.9 artifact types and verifies the post-migration state matches the expected output in testdata/v0.9-fixture-expected/.

See also:

• cmd-migrate, full nself migrate command reference
• Installation, fresh install guide
• Plugin-Install, plugin management reference

← Commands | Home →