Skip to content

Importing standalone runtime state

Unicity AOS keeps its product state under ~/.aos. It does not take ownership of ~/.astrid, and it never changes a standalone Astrid Runtime installation in place.

To copy compatible state deliberately, stop the standalone runtime and run:

aos migrate runtime --from "$HOME/.astrid"

On an interactive first run, aos can offer the same import. It never imports without confirmation.

What is copied

The importer copies persistent runtime state only:

  • user configuration, keys, secrets, databases, WIT content, principal homes, shared libraries, trusted distribution keys, system capsules, and CLI history;
  • durable audit and diagnostic logs, preserving the standalone runtime's provenance without treating those files as live coordination state;
  • content-addressed .wasm files from bin/;
  • the known etc/ configuration surface: runtime, MCP, gateway and HTTP configuration; layout version; group, invite, pairing and gateway revocation state; principal profiles; and system hooks.

Imported capsule installations are preserved without silently making an arbitrary standalone fleet part of the AOS distribution. For default, only packages selected by the bundled Community Edition manifest remain active. Non-CE capsule trees and non-default profiles are retained byte-for-byte under ~/.aos/runtime/imported/astrid-home-v1/ for deliberate later reactivation; provider configuration, principal data, runtime keys, audit data, and other persistent state remain at their normal runtime paths.

The etc/ list is deliberately explicit because it contains authorization and identity policy. If a newer runtime introduces an unknown configuration or top-level state path, the import stops and names that path instead of silently dropping it.

The run/ tree is deliberately not copied. Socket pathnames, PID, lock and readiness markers, deferred coordination, HUD health state, selected-session principal state, and transient tokens belong to the standalone daemon instance and must be regenerated by the bundled runtime. Copy-on-write working trees and old runtime executables are also excluded. AOS preserves the coordinated astrid, astrid-daemon, astrid-build, and astrid-emit executables bundled with its own release.

Integrity and recovery

The source directory remains unchanged, so the standalone installation is the rollback path until the operator chooses to remove it.

AOS builds the imported runtime in a private staging directory. Every copied file is recorded with its path, byte length, and canonical blake3:<hex> digest in a versioned receipt. AOS validates the staged tree before replacing its empty bundled runtime home. File data, directory entries, and the receipt are flushed before the transaction is considered complete on platforms that support directory synchronization.

Private target directories are normalized to owner-only access. Migrated state files become owner read/write, retaining owner execute only when the source was executable. This tightens permissive legacy modes without changing a byte or mode in the standalone source.

The product runtime's pre-import directory is retained as a transaction backup until the validated receipt is durable. If the process is interrupted, the next import either completes a fully validated replacement or restores that backup before retrying. A receipt whose files no longer match their recorded hashes is rejected.

The receipt is product state at:

~/.aos/migrations/astrid-home-v1.json

Keep the standalone runtime stopped throughout the import. The importer refuses to proceed while its system socket is present, when either root is a symlink, when the source and product roots overlap, when the AOS runtime home already contains user state, or when any source file would require following a symlink. It nonblockingly holds the standalone runtime's existing run/system.lock through validation, copying, receipt creation, and cutover without creating or rewriting source state. A stale PID file alone does not prove the daemon is running; the singleton lock is authoritative.

Only one import may run for an AOS home at a time. Concurrent attempts fail before staging or replacing runtime state, and a process crash releases the operating-system lock so the recovery path can run on the next attempt.