# Aion v0.0.3-beta.2 Linux Bootstrap Installer

Status: public beta artifact
Artifact: `artifacts/aion-installer-linux-amd64`
Target: Linux x86_64

## Purpose

The current Linux installer remains a conservative bootstrap script. It does not
try to be a native installer. It validates the machine, downloads the public
release manifest when needed, resolves the packaged `aion-ctrl` runtime engine,
configures the selected LLM provider, starts the public runtime, runs doctor,
and opens the packaged Linux launcher shell when it is present in the runtime
package.

The launcher then becomes the desktop-facing open path for the local runtime.
`aion-web` remains the product UI after the launcher opens the product.

## Artifact Shape

```text
releases/v0.0.3-beta.2/artifacts/aion-installer-linux-amd64
```

It is intentionally a shell bootstrap for the first launcher-enabled cut. A
compiled Go installer can replace it later without changing the release
contract.

The artifact includes a `--dry-run` mode so the release contract can be
validated without starting the local runtime.

Port checks are enabled by default. `--skip-port-check` exists only for
controlled smoke tests or advanced environments where the operator already knows
the default runtime ports are intentionally occupied or remapped.

For remote installs, the bootstrap requires provider credentials before `play`.
For `v0.0.3-beta.2`, the minimum supported inputs are:

- `--provider openai --openai-api-key <key>`
- `--provider groq --groq-api-key <key>`
- `--profile local-ollama`

## Supported Platform

- Linux x86_64
- Ubuntu 24.04 target
- Ubuntu 22.04 target
- Debian 12 target

Unsupported in `v0.0.3-beta.2`:

- Windows
- macOS
- Linux ARM64

## Requirements

- Docker daemon reachable
- Docker Compose v2
- 8 GB RAM minimum/recommended for the current public runtime
- 12 GB free disk under the selected Aion home
- one default remote path:
  - OpenAI key
  - or Groq key
- local Ollama only when intentionally using the advanced local profile
- free runtime ports:
  - `5000`
  - `5001`
  - `8000`
  - `8091`
  - `8092`
  - `19092`
  - `8082`
  - `9644`
  - `4566`

Additional port required only for `--profile local-ollama`:

- `11434`

## How It Resolves `aion-ctrl`

Resolution order:

1. `--aion-ctrl PATH`
2. `AION_CTRL_BIN`
3. executable `aion-ctrl` beside the installer
4. `aion-ctrl` in `PATH`
5. packaged artifact from `release.json` at `artifacts["aion-ctrl-linux-amd64"]`
6. `--aion-ctrl-url URL`
7. `AION_CTRL_URL`

The public path for `v0.0.3-beta.2` is the manifest-declared package artifact.
That tarball now contains:

- `aion-ctrl`
- `aion-launcher`
- `share/applications/aion.desktop`
- `share/icons/hicolor/512x512/apps/aion.png`
- `distribution/docker-compose.aion.yaml`
- `distribution/.env.example`
- bundled Localstack init assets

If no `aion-ctrl` binary can be resolved, the installer stops with an explicit
message. This is intentional: the bootstrap must not duplicate runtime logic
owned by `aion-ctrl`.

When a binary is found, the installer also looks for distribution assets in:

1. `distribution/` beside the `aion-ctrl` binary
2. `../distribution/` relative to the `aion-ctrl` binary

If found, it exports `AION_CTRL_DISTRIBUTION_ASSETS` before running
`aion-ctrl install` or `aion-ctrl play`. This keeps local builds such as
`aion-ctrl/build/aion-ctrl` working without changing the user's current
directory.

If the package also contains `aion-launcher` and packaged desktop assets, the
installer installs those launcher assets under the current Linux user and uses
them as the post-install open path. When the package comes from an older line
that does not yet contain the launcher, the installer falls back to the legacy
open wrapper.

## Usage

Local development smoke:

```bash
cd /home/lechitz/Projetos/github/Aion/aion
./releases/v0.0.3-beta.2/artifacts/aion-installer-linux-amd64 \
  --manifest releases/v0.0.3-beta.2/release.json \
  --aion-ctrl ../aion-ctrl/build/aion-ctrl \
  --dry-run \
  --skip-port-check \
  --no-open
```

Public-style invocation once artifacts are hosted:

```bash
./aion-installer-linux-amd64 \
  --provider openai \
  --openai-api-key "$OPENAI_API_KEY"
```

Environment equivalents:

```bash
AION_RELEASE_MANIFEST=https://lechitz.github.io/aion/releases/beta/release.json
AION_CTRL_BIN=/path/to/aion-ctrl
AION_CTRL_URL=https://example.invalid/aion-ctrl-linux-amd64.tar.gz
AION_HOME="$HOME/.aion"
AION_PROFILE=remote
AION_LLM_PROVIDER=openai
AION_LLM_MODEL=gpt-4.1-mini
AION_OPENAI_API_KEY=sk-...
```

## Runtime Flow

1. validate Linux x86_64;
2. validate RAM, disk, and ports;
3. resolve/download release manifest;
4. resolve/download the packaged `aion-ctrl` runtime engine, launcher assets, and distribution assets;
5. run `aion-ctrl version --json`;
6. run `aion-ctrl doctor --scope prerequisites --json`;
7. run `aion-ctrl update --manifest ... --json`;
8. stop when `--dry-run` is enabled;
9. run `aion-ctrl install`;
10. run `aion-ctrl config set ...` to persist the selected profile/provider settings through the runtime engine contract;
11. run `aion-ctrl config --json`, stop early if the selected config is not yet ready for first use, and surface provider-auth warnings when verification is temporarily unavailable;
12. show continuous terminal activity while the runtime is being prepared;
13. emit slow-path hints when image pulls or health checks are taking longer than usual;
14. run `aion-ctrl play` with a live progress indicator and context-aware failure hints;
15. run `aion-ctrl doctor --json` with a live progress indicator and context-aware failure hints;
16. install the packaged launcher desktop entry and icon when available, otherwise fall back to the legacy open wrapper;
17. open the launcher shell after bootstrap when launcher assets are present, otherwise fall back to the legacy browser open path.

## Failure Behavior

Failures are explicit and should point to the next corrective action. The
installer does not silently install Docker, does not mutate OS package state,
and does not attempt privileged operations.

For remote providers, readiness now has two layers:

- structural readiness: profile/provider/model/key fields are present and coherent;
- provider-auth verification: the packaged `aion-ctrl` can tell whether the selected credential was accepted, rejected, or could not be verified because the provider/network was unavailable.

That means:

- invalid remote credentials should stop the bootstrap before first use;
- temporary provider/network outages may still allow local runtime preparation, but the installer should surface a warning instead of pretending verification succeeded.

Docker and Compose prerequisite diagnosis is delegated to:

```bash
aion-ctrl doctor --scope prerequisites --json
```

That keeps the installer aligned with the same guidance used by the runtime
engine when it needs to distinguish:

- Docker not installed
- Docker installed but daemon stopped/unreachable
- current user missing Docker socket/group access
- Docker Compose v2 missing from the current Docker installation

If runtime health fails after startup, users should run:

```bash
aion-ctrl doctor
aion-ctrl repair
```

`v0.0.3-beta.2` uses the bootstrap-only exception. The runtime image set remains
on `v0.0.2-beta.12`, while the installer and packaged `aion-ctrl` move forward
to improve the Linux launcher-first open path.

## Deferred

- compiled Go installer;
- artifact signing;
- automatic Docker installation;
- native Linux installer;
- Windows/macOS installers;
- side-by-side runtime isolation on the same host.