Upgrade from v0.9

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

Upgrade from v0.9 to v1.1.0

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

Before you start

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 (the v0.9 bootstrap script) is no longer used.

What nself migrate does automatically:

Stops running containers.
Backs up your current project state to .nself/backup/{timestamp}/.
Moves nginx configs to nginx/sites/.
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>.

Step 1: Upgrade the CLI

macOS (Homebrew)

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

Linux

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

Step 2: Run the migration

Navigate to your v0.9 project directory and run:

cd ~/my-nself-project

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

# 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:

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

Step 3: Re-install plugins

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 (use your actual plugin list)
nself plugin install ai mux claw voice browser google notify cron

After running nself migrate run, the CLI prints a warning with the exact plugin list from your v0.9 .env and the commands to re-install them.

Step 4: Verify the stack

nself build
nself start
nself doctor

Command changes

v0.9 command	v1.1.0 equivalent	Notes
`./nself start`	`nself start`	Go binary, no bootstrap script
`./nself stop`	`nself stop`
`./nself status`	`nself status`
`./nself build`	`nself build`
`./nself logs`	`nself logs`
`./nself update`	`nself update`
`./nself doctor`	`nself doctor`
`./nself plugin install <name>`	`nself plugin install <name>`	New signed format
`./nself plugin list`	`nself plugin list`
`./nself plugin remove <name>`	`nself plugin remove <name>`
`./nself license set <key>`	`nself license set <key>`
`./nself license info`	`nself license info`
`./nself migrate`	`nself migrate`	New in v1.0.0
`./nself backup`	`nself backup`
`./nself restore`	`nself restore`
`./nself db migrate`	`nself db migrate`
`./nself db reset`	`nself db reset`
`./nself ssl renew`	`nself ssl renew`
`./nself config get <key>`	`nself config get <key>`
`./nself config set <key> <val>`	`nself config set <key> <val>`
`./nself env show`	`nself env show`
`./nself admin start`	`nself admin start`
`nself up`	`nself start` or `nself up`	`up` is now an alias

Environment file changes

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

v1.1.0: Cascade of env files:

.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)

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

Plugin name changes

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

v0.9 plugin name	v1.1.0 plugin name
`nself`	`ai`
`nself`	`claw`
`nself`	`mux`
`nself`	`voice`
`nself`	`browser`
`nself`	`google`
`nself`	`notify`
`nself`	`cron`
`nself`	`chat`
`nself`	`livekit`
`nself`	`recording`
`nself`	`moderation`
`nself`	`bots`
`nself`	`realtime`
`nself`	`media-processing`
`nself`	`streaming`
`nself`	`epg`
`nself`	`tmdb`
`nself`	`social`

Troubleshooting

Docker version too old

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

Port conflicts

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

Stop the conflicting service:

# macOS
brew services stop postgresql

# Linux
sudo systemctl stop postgresql

License key rejected after migration

nself license set nself_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
nself license info

Plugin name not found

v0.9 used nself prefix; v1.1.0 uses short names:

# Correct
nself plugin install ai

# Wrong
nself plugin install nself-ai

Migration fails midway

nself migrate rollback --list
nself migrate rollback

nself doctor reports issues after migration

nself doctor --full
nself doctor --check-legacy

Rollback

# List available backups
nself migrate rollback --list

# Restore the most recent backup
nself migrate rollback

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

Automated testing

The migration path is covered by a CI fixture (cli/internal/migration/testdata/v0.9-fixture/) that runs on every PR via .github/workflows/migration-fixture.yml.