Installation And Lifecycle

Astraeus is installed from a target-specific product bundle. A standard bundle contains the source-free Astraeus wheel, its complete locked dependency wheelhouse, curated examples and resources, the local Console, user AI skills, and the installer needed to manage the product lifecycle.

Choose The Correct Bundle

The current package targets are:

Target	Required host Python
Linux x86-64 (manylinux_2_28)	CPython 3.11 x86-64
Windows x86-64	CPython 3.11 x86-64

Use the bundle qualified for your operating system, architecture, and CPython version. The installer refuses a foreign target by default.

You need:

• a complete CPython 3.11 installation capable of creating virtual environments
• enough user-writable space for the versioned runtime and your run outputs
• the files supplied together with the release:
• astraeus-<version>-<target>.zip
• its matching .sha256 sidecar
• install.py
• astraeus_manager.py
• release-envelope.json
• release-signature.json
• astraeus-bootstrap-verifier-<target>.zip

Keep the supplied release folder together. Do not rename individual files.

Offline Installation

From the directory containing the supplied files, run:

python install.py install --bundle astraeus-<version>-<target>.zip

On Windows, py -3.11 can be used instead of python when that is how CPython 3.11 is selected:

py -3.11 install.py install --bundle astraeus-<version>-<target>.zip

The installer performs the following before making the version active:

1. authenticates the signed release envelope before trusting or extracting the archive
2. verifies the archive sidecar, release inventory, and bundled checksums
3. checks that the bundle matches the selected CPython and host target
4. creates an isolated, versioned environment using only bundled wheels
5. runs a product smoke test, including version, resources, and RunSpec validation
6. installs the user launcher and records the active installation

The command prints a JSON result. A successful install reports "passed": true and identifies the installed version, launcher, installation root, and data root.

Default Locations

Purpose	Linux	Windows
Managed product versions	~/.local/share/astraeus	%LOCALAPPDATA%\Astraeus
User data	~/Astraeus	%USERPROFILE%\Astraeus
Launcher	~/.local/bin/astraeus	%LOCALAPPDATA%\Astraeus\bin\astraeus.cmd

The user data root contains separate workspaces, runs, configuration, and logs directories. It is deliberately outside the managed product versions.

Use --install-root, --data-root, or --launcher-dir on the initial install when your environment requires different locations. Use the same --install-root on later lifecycle commands if you changed it from the default.

If the launcher directory is not already on PATH, either add it to PATH or invoke the launcher by its full path.

Confirm The Installation

Check the active product:

astraeus --version
astraeus --help

Inspect the managed installation state:

python install.py status

Run the installation diagnostic:

python install.py doctor

status reports the active and retained versions, launcher, and user data locations. doctor additionally checks required files, active-state and manifest version consistency, the active product launcher, recorded release authentication identity, redacted licence status for an entitlement-enforcing product, and whether the user data directories are writable. Its observations include available and total storage for the managed install and registered user-data locations. A storage observation that cannot be made appears under warnings; installation inconsistencies appear under issues and produce a nonzero exit status.

The bundle digest, signing-key ID, and envelope digest shown by doctor are the non-secret provenance recorded when the release was installed. They identify the authenticated installation event rather than performing a new signature check. A recorded last_failure provides context about an earlier lifecycle operation and does not by itself make the current installation unhealthy.

You can also confirm that packaged examples and supporting data are available:

astraeus resources list

Activate Astraeus

A source-free product installation must be activated before it starts a new simulation or planning run. For an online commercial licence, enter the supplied activation key at the secure prompt:

astraeus activate --activation-key

For non-interactive setup, place the key in a deliberately named environment variable and identify that variable to Astraeus:

astraeus activate --activation-key-env ASTRAEUS_ACTIVATION_KEY

Clear the variable after activation. The key is exchanged for locally verified authorization; it does not need to be present during normal execution.

For an offline licence, protect the supplied entitlement file and install it directly:

astraeus activate --license-file <signed-entitlement.json>

An invitation-based trial uses the same secure-prompt pattern:

astraeus activate trial

Inspect the current state and the recommended action at any time:

astraeus license status

valid, refresh_due, and grace states permit execution until their signed limits. Refresh an online commercial licence explicitly with astraeus license refresh; renew an offline licence by activating its replacement file. Use astraeus license deactivate to remove local authorization and, for an online licence, request deactivation of its refresh session.

Activation and refresh need service access only for online licences. Execution uses the signed local state, while validation, preflight, help, status, Monitor, review, reporting, and access to existing results remain available without an active entitlement.

Continue with the first core run after installation and activation are complete.

Optional Online Acquisition

Offline installation is the baseline. Astraeus also includes a client for downloading one exact release from an authenticated distribution index and then passing the verified archive through the same offline installer.

Online acquisition is available only when your Astraeus provider gives you an index URL, version, channel, and download credential.

The credential is read from an environment variable rather than a command-line argument. By default that variable is ASTRAEUS_DOWNLOAD_TOKEN.

python install.py online --action install --index-url <provided-index-url> --version <exact-version>

For an explicitly supplied prerelease, also select its channel and opt in:

python install.py online --action install --index-url <provided-index-url> --version <exact-version> --channel alpha --allow-prerelease

The available actions are download, install, and update. A download is resumable, but activation occurs only after the complete archive and sidecar pass verification. --token-env selects a differently named credential variable when required by your environment.

Update

Keep the new archive and its matching sidecar together, then run:

python install.py update --bundle astraeus-<new-version>-<target>.zip

An update is side-by-side and transactional:

• the current version remains active while the new environment is prepared
• compatibility and smoke checks run before activation
• a failed pre-activation update leaves the current version active
• one previous version is retained for rollback
• user data locations remain in place

Confirm the result with status, doctor, and astraeus --version.

Roll Back

To reactivate the retained previous version:

python install.py rollback

The previous version must still be retained. Astraeus smoke-tests it before switching the active launcher. Rollback changes only the active product version; your workspaces, run outputs, configuration, and logs remain in place.

Artifacts and RunSpecs created by a newer product may not be compatible with an older version. Preserve the product version and RunSpec snapshot recorded in each run bundle when reviewing results across an update or rollback.

Uninstall

Remove an inactive retained version by its package version:

python install.py uninstall --version <version>

The active version cannot be removed individually. Roll back first, or remove all managed product binaries and the launcher:

python install.py uninstall --all

--all preserves the registered user data directories, including workspaces, run outputs, configuration, and installation logs. Maintain independent backups of important studies according to your data policy.

Troubleshooting

Symptom	What to check
Archive or sidecar verification fails	Confirm the ZIP and .sha256 came from the same release and were not renamed or modified. Obtain a fresh copy rather than bypassing verification.
Target or Python mismatch	Use the package for your operating system and x86-64 architecture, and select CPython 3.11.
Python cannot create the environment	Confirm the selected CPython installation includes venv support and is writable/executable for your user.
astraeus is not found after installation	Add the launcher directory shown by the installer to PATH, or invoke that launcher by its full path.
The installer says Astraeus is already installed	Use update for a newer verified bundle; do not run a second initial install into the same root.
doctor reports missing or unwritable paths	Review the reported path and permissions. If managed product files are damaged, reinstall the same verified bundle rather than copying files between versions.
doctor reports a version or recorded-authentication mismatch	Preserve the diagnostic output. Use rollback when a healthy retained version is available, or reinstall the same verified bundle; do not edit installation state or managed manifests.
doctor reports only a storage warning	Confirm that the reported location is mounted and accessible. Use RunSpec preflight to estimate capacity for a particular workload.
Rollback says no previous version is available	Only one previous version is retained, and it exists only after a successful update. Install a verified bundle explicitly if that version is needed again.
Online acquisition rejects the request	Confirm the provided URL, exact version, channel, credential variable, and explicit prerelease opt-in where applicable.

Do not disable bundle verification or copy files manually into a managed version directory. If diagnosis does not identify a safe correction, preserve the JSON error and the installation log under the user data root when requesting support.