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

Apple Silicon technical preview¶

Technical preview

An Apple Silicon preview build is available by arrangement. macOS is not yet a supported release target at the same level as Windows and Linux. Contact Vectra Labs for access and the current installation instructions.

Install From A Trial Download¶

An approved trial email contains two separate credentials:

Download Astraeus opens a private page where you choose the Windows or Linux package. The link is valid until the date shown in the email.
the trial invitation code activates the installed product and starts the trial. Downloading Astraeus does not start the trial.

Download the package for the computer where you will run Astraeus. Its name ends in -package.zip. A package from an approved link issued before this naming update may instead end in -customer.zip; both use the same structure. Extract it into a new folder before running anything; the extracted folder contains the product bundle and all of the installer and release-authentication files listed above.

From that extracted folder, run the matching command from Offline Installation. Then follow Activate Astraeus, choose the trial command, and paste the invitation code only when the secure prompt asks for it.

Keep the approval email private. If its download action has expired or no longer opens the platform page, contact Vectra Labs for a replacement. Reusing an older email after a replacement is sent will not work.

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:

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

The installer names each phase as it starts and prints a heartbeat while a slow phase is still running. On success it reports the installed version, launcher, and next command in a short summary. Use --json when a script needs the full machine-readable lifecycle result.

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.

On Windows, the installer adds its launcher directory to your user PATH. Open a new terminal after the first installation, then use astraeus directly. On Linux, the installer reports the launcher directory if it is not already on PATH; add that directory once or invoke the reported 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 and launcher. 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. The default output is a concise customer summary. Add --json to either command for complete paths, storage observations, warnings, issues, and recorded provenance. Installation inconsistencies 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

The interactive prompt displays an asterisk for each entered character without revealing the invitation itself. Paste the invitation code normally and press Enter. Surrounding whitespace and line wrapping copied from an email are ignored.

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	On Windows, close and reopen the terminal so it receives the updated user `PATH`. On Linux, add the launcher directory shown by the installer to `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, add --json to the relevant lifecycle command and preserve that result with the installation log under the user data root when requesting support.