Install Aion — Ablative docs

Install the public release

Use a Unix host with Cargo and Rust 1.89 or later. Aion uses Rust edition 2024 and the AGPL-3.0-only licence.

cargo install aion-cli --version 0.31.0 --locked
aion --version
aion --help

aion-cli: Cargo package that installs the aion executable.
AION_HOME: Process setting for the server home. Default ~/.aion. This contains the discovered config, logs and process record; store.data_dir selects durable storage.

The crate page provides the public package and its release metadata. Continue with your first workflow for an AWL greeting supported by that release.

Install with JWT authentication

The default build leaves out JWT authentication. Add the auth feature when installing a server that must validate JWTs. On main, crates/aion-cli/Cargo.toml:146–149 defines the default and optional feature sets.

cargo install aion-cli --version 0.31.0 --locked --features auth

Configure the key URL and namespace claim in auth and Lys. Reinstalling with the default feature set changes the available authentication mode.

Using main

The published crate predates the main features described here, despite sharing their package version. Main adds venues, connected-worker inspection, package-row migration and plural gRPC listeners. The release reference explains these differences.

With repository access, run this from the checkout root. Choose the source revision before building and retain it with the installed binary.

cargo install --path crates/aion-cli --locked --features auth
aion --version
aion --help

Choose an update target

A bare update selects the crates.io release and can replace a newer build from main when installation proceeds. Pass an explicit version for a published target, or reinstall from the selected checkout for main. Equal version strings can report already current despite different commits.

aion update --version 0.31.0

Registry target: On main, crates/aion-cli/src/update.rs:81–85 resolves an omitted version through update_index::latest_stable; lines 329–359 invoke cargo install aion-cli --version with default features. An explicit version still targets the registry.
Equal versions: On main, crates/aion-cli/src/update.rs:273–300 compares package version strings in already_current(). Retain the source commit and executable identity as well as the version.
JWT build: On main, crates/aion-cli/Cargo.toml:146–149 omits auth from the defaults. Reinstall with --features auth to retain JWT verification.

Check for an existing server

Read status first. Reuse an existing server’s endpoint and namespace when continuing the tutorial.

Report which server is actually running: the pid-file record, the live build identity from its own listener, and readiness — each layer's absence reported as its own distinct state

aion server status [OPTIONS]

--config <CONFIG>: Path to the TOML server configuration file. Used to resolve the store path and, when no pid file exists, the address to probe

Start a local server

When the home has no running server, the bare launcher starts one in the background. It prints the configuration, data directory, log, process identity and console URL. This example leaves the browser closed.

aion server status
aion --no-open

On first boot with no discovered config, the launcher writes a commented config under Aion home. The starter enables deployment and the local worker listener. These choices are written into that file.

The console is embedded in the executable. Open the URL printed by the launcher.

Use a foreground process

An explicit config keeps the server in the terminal. Use the config generated by your installed release. The configuration reference describes the newer main build.

aion server --config aion.toml

Read running the server for logs, readiness and shutdown.