Migrating from v0.6 to v0.7

v0.7 introduces more flexible secret policies and snapshot groups for saved checkpoints and branching. It also improves migration of older configurations and checks for incompatible settings before launch or downgrade. Use v0.7.3 or a later compatible patch release. Earlier v0.7 releases have compatibility gaps addressed in v0.7.3.

What changed and why

Secrets have separate controls for credential substitution, unchanged placeholders, and violation handling. This allows more precise policies, but changes how disabled substitution locations behave.
Snapshot groups keep checkpoints immutable, so overwriting a named member is no longer supported. Capture a new member instead.
Compatibility checks catch unsupported state earlier. Saved configurations migrate automatically; launch and downgrade checks reject settings the selected release cannot represent.

What the upgrade affects

Component	What to expect
Saved sandbox configurations	Migrated in place, including image, mount, CPU, and secret settings in saved and recorded active configurations. Valid sandboxes do not need recreating.
Application code and configuration files	Not rewritten. Review the changes below.
Older SDK applications and CLI jobs sharing `MSB_HOME`	Stop and upgrade them together. Older processes can write incompatible records or fail to read the upgraded database.
Running sandbox VMs	Can remain running during migration. They keep their runtime and guest code until restarted.

Supported older runtimes remain usable for existing operations; newer features may require an upgrade. Selecting an older runtime does not restore older SDK access to an upgraded database. Cloud users do not run this local migration. Cloud compatibility is handled by the service and requires server support, not just an updated SDK.

Upgrade your installation

Stop older SDK applications and CLI jobs sharing the home.
Back up the home. Stop its sandboxes while copying their disks for a consistent backup.
Update SDK dependencies, lockfiles, and the installed runtime. Keep msb and libkrunfw from the same bundle. A home-installed runtime takes precedence over Python and Node bundles; updating the SDK alone may still select it. See runtime setup.
Apply the code and configuration changes below, then verify sandbox startup, saved data, and authenticated requests before removing the backup.

For Python:

python -m pip install --upgrade 'microsandbox>=0.7.3,<0.8'

Use your package manager for other SDKs. For an installed runtime, msb self update installs the latest release; it cannot select a specific version.

Review secret policies

Saved policies migrate automatically. Update code and configuration files using these previous settings:

v0.6 setting	v0.7 equivalent
`injection`	`substitution`
`query_params`	`query`
Separate `headers` and `basic_auth`	`headers`, enabled if either old switch was enabled
Passthrough destinations in the violation policy	Separate passthrough destinations

Review these behavior changes when using a v0.7 runtime:

Basic Auth shares the header switch. An old Basic-Auth-only policy now also permits substitution in other headers.
Disabled locations no longer imply passthrough. A body placeholder is blocked when body substitution is disabled, unless its destination has explicit passthrough permission. Enable body substitution to send the credential; allow passthrough to send the placeholder unchanged. Passthrough applies to the destination, not only the body.
At least one substitution location must be enabled. All-disabled policies migrate, but cannot launch until you enable a location or remove the policy.
Explicit global passthrough defaults are preserved, including for future secrets. Per-secret blocking actions override them.

See SDK examples and YAML configuration.

Update snapshot code

Local snapshot group members are immutable. force=True fails even for a new name.

Before: v0.6

from microsandbox import Snapshot

snapshot = await Snapshot.create(
    "checkpoint", from_sandbox="workbench", force=True
)

Use a generated or unique name and leave force=False:

After: v0.7

from microsandbox import Snapshot

snapshot = await Snapshot.create(from_sandbox="workbench")

To reuse a name, call Snapshot.remove() first. Removal checks dependencies. If the next capture fails, the removed checkpoint is lost. Use a new name to keep the previous checkpoint. This applies to installed group members; direct archive output can still be overwritten. See snapshot groups.

Restore external resources

For restore and branch, supply host mounts, published ports, and custom vsock routes explicitly. Snapshots do not copy host files or restore external connections. Full snapshots require compatible runtime and firmware versions.

Check flush behavior

Policy	Behavior
`auto` (default)	Flushes running disk-only snapshots. Full snapshots, branches, and pause retain pending writes in memory.
`required`	Requires writes on disk, useful when restoring only a full snapshot’s disks. Fails for stopped or crashed sandboxes. Paused sandboxes need a prior acknowledged flush.

Restart older runtimes before live capture requiring the new flush capability. Go also needs a policy-aware native library. See Guest flushing.

Review other application changes

Runtime setup

Local creation no longer downloads missing runtimes. Call the explicit setup helpers first. Python, TypeScript, and Go setup APIs were also renamed in v0.7.0; see the old-to-new API mapping.

HTTPS hostname rules

Strict hostname checking is on by default in v0.7.3. Hostname-only HTTPS allow rules need TLS interception. IP, CIDR, group, and default allow rules are unaffected. To opt out, use --net-strict=false or network.strict: false. Go replaces Strict with DisableStrict. See hostname rules and HTTPS.

Shutdown and connection limits

Graceful stop: no default deadline. Set a timeout where needed; expiry does not force-kill the sandbox.
Connections: unlimited by default for single-tenant sandboxes; 1,024 each for TCP and UDP in multi-tenant sandboxes. Zero means unlimited. maxConnections remains a deprecated TCP-only alias.

Rust API changes

API	Change
`LocalBackend::lazy()`	Now returns `Result`.
`LocalBackendBuilder::build_lazy()`	Now returns `Result`.
`SdkConfig`	Removed.
`load_sdk_config()`	Removed.
`SnapshotSpec`	New field: `guest_flush`.
`SecretsConfig`	New field: `passthrough_hosts`.
`CloudSecretsConfig`	New field: `passthrough_hosts`.

Handle the new Result returns. In struct literals, supply the new fields or use ..Default::default() where supported. In exhaustive patterns, include the fields or ... For replacements for the removed APIs, see configuration and runtime setup.

Recover from a migration error

If v0.7.0–v0.7.2 reports unsupported persisted sandbox configuration, upgrade to v0.7.3 and retry first. A v0.7.2 database can upgrade directly; no downgrade to v0.6 is needed. A malformed saved configuration aborts the whole migration before converted rows are written. The error names the sandbox and configuration column.

Stop SDK applications sharing the home and keep a consistent backup.
Repair the named configuration using the previous SDK/CLI that can read it. Remove the sandbox only if its data is no longer needed.
Retry the upgrade.

Do not delete the database, edit migration history, or skip the row. If previous tools cannot read it, report the error and SDK/runtime versions. Do not share unredacted secrets.

Downgrade to an older release

Run msb self downgrade from the newer CLI before replacing it, including through Homebrew, or reinstalling older SDKs. Only the newer CLI contains the rollback steps for its migrations.

msb self downgrade 0.6.18

Stop applications sharing the home and keep the default backup enabled.
Schema rollbacks and v0.6 configuration rewrites require stopped sandboxes. If the command reports active sandboxes, stop them and retry.
Incompatible settings are rejected before changes. For example, v0.7.0–v0.7.2 cannot preserve global secret passthrough defaults, even empty lists. Force flags do not bypass these checks.

A database downgrade does not make every newer snapshot or feature usable by an older release. See downgrade options.

Database schema is newer than this msb binary

After replacing a v0.7 binary with v0.6, even msb list can report:

database schema is newer than this msb binary

Attempting downgrade from the older CLI can instead report:

local database was updated by a newer msb or does not contain a valid migration prefix

After a binary-only downgrade, these errors indicate newer database state, not necessarily corruption. If you already uninstalled the newer CLI:

Reinstall the release that last migrated the home, or a later compatible release, with its matching libkrunfw. Keep the existing MSB_HOME.
Check msb --version to confirm your shell is invoking the newer binary.
Follow the stopped-sandbox and backup requirements above, then run msb self downgrade 0.6.18 from that newer binary.
After the command succeeds, verify msb list with the target release before returning SDK applications to that version.

Do not delete the catalog or edit migration history to bypass the refusal. If the restored newer CLI also rejects the catalog, report the error and the versions involved.

Snapshot groups can block downgrade

Downgrading to a release without group support is refused while groups, even empty ones, or duplicate snapshot identities remain. The error begins snapshot groups prevent downgrade. New v0.7 captures use a group by default, including disk snapshots. Existing v0.6 snapshots remain ungrouped when upgrading. To proceed, export the snapshots you need, verify the backup, then remove the blocking snapshots and empty groups before retrying the downgrade. Exports preserve snapshots for later use with v0.7. They do not convert snapshots for v0.6.

Back up snapshots before downgrading

Use the newer CLI and follow the backup requirements above. This example uses one snapshot, app:ready.

Export outside MSB_HOME, including ancestors and the image:

mkdir -p "$HOME/msb-snapshot-backups"
msb snap export app:ready \
  --output "$HOME/msb-snapshot-backups/app-ready.msb" \
  --with-parents --with-image

Import and verify with the newer CLI in a separate home:
recovery_home=$(mktemp -d) MSB_HOME="$recovery_home" msb snap import \ "$HOME/msb-snapshot-backups/app-ready.msb" --group recovered MSB_HOME="$recovery_home" msb snap verify recovered
Keep the recovery home and archive, and test a restore before removing the original. Import into a separate home to avoid creating another group that blocks downgrade.
After confirming the backup, remove the original snapshot:
msb snap rm app:ready msb snap ls --group app
For multiple members, export each snapshot you need. Remove children before parents, selecting another head with msb snap head app:<member> before removing the current head. Do not force past dependency errors.
Once the group is empty, move its remaining directory outside the snapshot store. For the default location:
mv "${MSB_HOME:-$HOME/.microsandbox}/snapshots/app" \ "$HOME/msb-snapshot-backups/app-empty-group" msb self downgrade 0.6.18
Adjust the path for a custom snapshot location. Repeat for other groups before downgrading; ungrouped duplicate instances may also need cleanup.

Import after returning to v0.7

With a compatible v0.7 CLI installed again:

msb snap import "$HOME/msb-snapshot-backups/app-ready.msb" --group app
msb snap ls --group app

Migration guides

Releases

Past updates

Migrating from v0.6 to v0.7

What changed and why

What the upgrade affects

Upgrade your installation

Review secret policies

Update snapshot code

Restore external resources

Check flush behavior

Review other application changes

Runtime setup

HTTPS hostname rules

Shutdown and connection limits

Rust API changes

Recover from a migration error

Downgrade to an older release

Database schema is newer than this msb binary

Snapshot groups can block downgrade

Import after returning to v0.7

​What changed and why

​What the upgrade affects

​Upgrade your installation

​Review secret policies

​Update snapshot code

​Restore external resources

​Check flush behavior

​Review other application changes

​Runtime setup

​HTTPS hostname rules

​Shutdown and connection limits

​Rust API changes

​Recover from a migration error

​Downgrade to an older release

​Database schema is newer than this msb binary

​Snapshot groups can block downgrade

​Import after returning to v0.7

What changed and why

What the upgrade affects

Upgrade your installation

Review secret policies

Update snapshot code

Restore external resources

Check flush behavior

Review other application changes

Runtime setup

HTTPS hostname rules

Shutdown and connection limits

Rust API changes

Recover from a migration error

Downgrade to an older release

Database schema is newer than this msb binary

Snapshot groups can block downgrade

Import after returning to v0.7