Aegis documentation

#thor — artifacts, runtime and installation

Thor keeps the pinned third-party artifacts in vendor/apps and the bundled CPython runtime in runtime/python, and it owns the installer that turns a fresh supported host into an Aegis server.

Nothing here uses the system Python. bin/aegis and bin/thor both resolve the interpreter from runtime/python/current; bin/aegis-prepare is the one bootstrap script that runs on the host Python, and all it does is call thor runtime prepare.

Output is human-formatted throughout: these commands print their own lines and tables and never consult the global --json flag. Exit codes follow Conventions: 0 success, 1 failure, 2 usage, 130 Ctrl+C.

#Where things live

PathContent
config/thor/apps.jsonthe artifact catalog: group, name, version, URL and SHA256
config/thor/runtime.jsonthe pinned CPython build, required modules and Python packages
vendor/apps/<group>/<name>/<version>/<file>every downloaded source or binary artifact
runtime/python/<version>the extracted CPython tree
runtime/python/currentsymlink the launchers resolve
storage/temp/downloads.part files while a transfer is in flight
storage/apps/state.jsonwhen each artifact and the runtime were last verified

The state file is history, not truth: thor apps always inspects the disk, so an artifact deleted by hand is reported as missing even though the state file still remembers it.

#Artifact commands

#aegis thor apps

Lists every entry in config/thor/apps.json, grouped like the vendor tree, with a verdict per artifact.

bash
aegis thor apps --verify
Argument / optionDefaultMeaning
--verifyoffhash every present artifact and report a mismatching one as stale

Without --verify the command checks file presence only (downloaded or missing). The summary counts missing and stale together as "not downloaded", and adds a separate stale count when --verify finds one.

Examples:

bash
aegis thor appsaegis thor apps --verify
text
Aegis apps57 total · 50 downloaded · 7 not downloaded · 1 stale  APP             VERSION   STATUS  ─────────────────────────────────dns/    bind            9.21.27   downloadedweb/    nginx           1.30.6    downloaded    php             8.5.12    missingweb/nginx-modules/    geoip2          3.4       stale

stale is printed in yellow and missing in red on a terminal; piping the command leaves the same words in plain text, which is why thor apps | grep missing works.

#aegis thor download

Fetches one artifact, or the whole catalog, into vendor/apps.

bash
aegis thor download app --force
Argument / optionDefaultMeaning
appevery catalog entryan application name (nginx) or a full key (web/nginx-modules/geoip2)
--forceoffdownload even when the file is present and its SHA256 already matches

The download goes to storage/temp/downloads/<file>.part; only after the SHA256 matches is it moved into vendor/apps with an atomic replace. A corrupt transfer can therefore never leave a truncated artifact in the catalog tree. An existing file with the wrong checksum is fetched again even without --force; an existing file with the right checksum is skipped.

The mirror from [thor] mirror is tried first, using source_template for the path, and the upstream url from the catalog is the fallback. Whichever copy arrives must match the pinned SHA256.

A single application shows a byte progress bar. A batch (no argument) shows one timeline with a dot per application. A failure is reported and the batch continues; the command exits 1 at the end if anything failed.

Examples:

bash
aegis thor download nginxaegis thor download web/nginx-modules/geoip2aegis thor download --force
text
nginx 1.30.6  [██████████████████████████████]  100%✔ web/nginx 1.30.6ℹ 1 downloaded, 0 already present

With no argument the batch draws one timeline on stderr and finishes with:

text
ℹ 57 downloaded, 0 already present

Unknown names stop immediately:

text
✖ unknown app: nginxx

#Runtime commands

#aegis thor runtime prepare

Installs the bundled runtime end to end: download the architecture-specific CPython artifact, verify it, extract it, point current at it, then install the declared Python packages into that runtime's own site-packages.

bash
aegis thor runtime prepare --force
Argument / optionDefaultMeaning
--forceoffre-extract the interpreter and reinstall every declared package

Without --force, a runtime that already passes every check is left alone (Runtime is installed). A cached archive that still matches its checksum is used instead of downloading again. The extraction happens in a staging tree and is swapped into place, because overwriting a running interpreter fails with ETXTBSY.

No compiler is involved: the artifact is a pinned standalone build. The host Python is never modified.

Examples:

bash
aegis thor runtime prepareaegis thor runtime prepare --force
text
ℹ Preparing to downloadDownloading Python 3.15.2  [██████████████████████████████]  100%✔ Python 3.15.2 ready  /etc/aegis/runtime/python/3.15.2ℹ 4 package(s) installed  certbot==5.10.0, certbot-dns-rfc2136==5.10.0, meson==1.7.2, cmake==3.31.6

On a prepared host:

text
✔ Runtime is installed

bin/aegis-prepare is the same operation for a host where bin/aegis cannot run yet:

bash
./bin/aegis-prepare./bin/aegis-prepare --force

#aegis thor runtime status

Checks the interpreter, the current symlink, the reported Python version, the required standard-library modules and every package declared in runtime.json.

bash
aegis thor runtime status
Argument / optionDefaultMeaning
——no arguments or options

Each check prints one status line with its detail underneath. Any failed check exits 1, so the command can gate an installation.

Examples:

bash
aegis thor runtime statusaegis thor runtime status && aegis keeper start
text
✔ interpreter  /etc/aegis/runtime/python/3.15.2/bin/python3✔ current  /etc/aegis/runtime/python/current✔ version  Python 3.15.2✔ modules  ssl, sqlite3, zlib, bz2, lzma, ctypes, hashlib, json, asyncio✔ package:certbot  5.10.0✔ package:certbot-dns-rfc2136  5.10.0✔ package:meson  1.7.2✔ package:cmake  3.31.6ℹ runtime is ready

A missing runtime stops after the first check:

text
✖ interpreter  /etc/aegis/runtime/python/3.15.2/bin/python3

#Installer commands

The installer is mounted at the top level, not under thor: aegis setup, aegis install, aegis configure and aegis build.

#aegis setup

Asks the installation questions and writes config/server.toml, without building or changing anything else.

bash
aegis setup --domain DOMAIN --hostname NAME --timezone ZONE --confirm
Argument / optionDefaultMeaning
--domainexisting value, or a promptprimary domain, for example example.com
--hostnameexisting value, or the detected host nameserver host name
--timezoneexisting value, or UTCIANA timezone, for example Europe/Bucharest
--confirmoffaccept the detected primary IPv4 without asking

Answers are merged into server.toml, never used to replace it: generated values such as the mail database password survive a re-run. The questions cover the primary IP, geolocation, domain, ACME e-mail, host name, timezone, applications and the database backend for Postfix/Dovecot. Application choices are written to [apps] install.

Examples:

bash
aegis setupaegis setup --domain example.com --hostname srv1.example.com --timezone Europe/Bucharest --confirm
text
Server setup  Answers are written to config/server.toml.  public_ip: 203.0.113.10  geo: Bucharest, Romania  primary_domain: example.com  acme_email: admin@example.com  hostname: srv1.example.com  timezone: Europe/Bucharest  apps: 6 selected  backends: postfix=pgsql  write: /etc/aegis/config/server.toml✔ configuration written to /etc/aegis/config/server.toml

An invalid value stops before anything is written:

text
✖ primary_domain: invalid domain: example✖ setup cancelled

#aegis install

Runs the whole installation: setup questions, host checks, builds of the selected applications and their libraries, configuration, provisioning, service startup and the closing certificate.

bash
aegis install app -v|--verbose|--v -y|--yes              --domain DOMAIN --hostname NAME --timezone ZONE --confirm
Argument / optionDefaultMeaning
appevery application selected in server.tomlinstall and configure one application, plus the libraries it needs
-v, --verbose, --voffdetailed per-task output instead of the three-line live bar; also selected automatically when stdout is not a terminal
-y, --yesoffskip the setup questions and trust config/server.toml
--domainexisting value, or a promptpre-answer the primary domain
--hostnameexisting value, or detectedpre-answer the host name
--timezoneexisting value, or UTCpre-answer the IANA timezone
--confirmoffaccept the detected primary IPv4 without asking

--yes is meant for a host that already has a server.toml with setup.primary_ip; without one the command stops with:

text
✖ no server.toml yet; run `aegis setup` first

--yes skips the wizard, so --domain, --hostname, --timezone and --confirm only matter when it is not given.

A named application pulls in its build dependencies (for nginx: OpenSSL, pcre2, zlib and libmaxminddb), but only that application is configured. The mail facade is added automatically when Postfix or Dovecot is named. With no argument, every application selected in server.toml is built and configured in dependency order.

Provisioning, the Rust binaries, the keeper and the finishing certificate/link step run in both forms; only the list of configured applications changes.

Examples:

bash
aegis installaegis install nginxaegis install nginx --yes --verboseaegis install --domain example.com --timezone Europe/Bucharest --confirm

A successful run ends with the closing report:

text
-> Well done-> Aegis installation has been completed  1 applications have been installed  Install path:     /aegis/appsDomain example.com has been successfully configured  Zone path:        /aegis/data/bind/zones/example.com.db  SSL path:         /aegis/data/certbot/live/example.com/fullchain.pem  IP SSL path:      /aegis/config/ssl/local/203.0.113.10/cert.pem  Configured timezone: Europe/Bucharest  Primary IP:       203.0.113.10  Panel:            http://203.0.113.10:9981What now:  aegis keeper services          services and their pids  aegis cubes list               management commands per application  aegis cubes nginx expose       where nginx lives and how it runs  aegis configure [app]          re-render configuration and restart

An interruption is reported as installation stopped with exit code 130; a failed step ends with installation aborted and exit code 1. A re-run prints already installed: … for applications whose prefix still carries a matching fingerprint.

#aegis configure

Re-runs the configuration half without building anything: every selected cube's configure(), then provisioning, the Rust binaries, the keeper and the finishing certificate/link step.

bash
aegis configure app -v|--verbose|--v
Argument / optionDefaultMeaning
appevery application selected in server.tomlconfigure only this application
-v, --verbose, --voffdetailed per-task output instead of the live bar

This is the command to run after editing aegis.toml, server.toml or a template. The cube decides what changed: it re-renders a file only when its content differs and restarts only the daemons that need it.

Examples:

bash
aegis configureaegis configure nginxaegis configure -v

With -v, or when stdout is not a terminal, the run prints one block per step:

text
⬢ configure/nginx  status: installed  source: cube  elapsed: 1.42s  ✔ configure  ok  1.42s⬢ services/keeper  status: installed  source: keeper  elapsed: 4.01s  ✔ boot       ok  0.02s  ✔ start      ok  0.31s  ✔ verify     ok  3.66s

With nothing selected there is nothing to configure:

text
✖ nothing installed yet: run `aegis install` first

#aegis build

Compiles the Rust workspace and publishes every aegis-r-* binary into bin/, where the Python side, the keeper registry and the panel expect it.

bash
aegis build
Argument / optionDefaultMeaning
——no arguments or options

The toolchain comes from the Thor catalog (runtime/rust) and is unpacked under the application tree on first use. Cargo's own cache makes a second run cheap. Binaries are copied to a .new name and renamed over the destination, so a running daemon keeps its old inode instead of failing the build with "Text file busy".

Examples:

bash
aegis buildaegis build && aegis keeper services
text
✔ aegis-r-bird -> /etc/aegis/bin/aegis-r-bird

A missing toolchain or a compile error is reported and exits 1:

text
✖ cargo failed: error: could not compile `aegis-r-bird`

#What an install pass does to the host

The installer runs steps in the order it lists them. A step holds ordered tasks; the first failing task fails the step, and the step's failure policy decides whether the run stops (BREAK) or continues (CONTINUE).

StepEffect on the host
verification/serverreads the host only: distribution support, hardware, network, outbound HTTPS, OS and kernel. Nothing is written.
verification/vendorreads the catalog, reports artifacts that are not downloaded yet, hashes the present ones. Nothing is written.
core/requirementsensures the base command-line tools and the CA trust store, creates the installation tree with mode 0755, then writes and removes a probe file in every directory to prove it is writable. Stops the run on failure.
base/toolchaininstalls the compiler, build tools and C headers through the host package manager. Only added when something has to be built.
apps/<name>one step per pending application and dependency, in dependency order: artifacts, requirements, prepare, configure, compile, install, optional extensions, verify. Installs system packages, groups and users declared by the profile.
configure/<name>calls the cube's configure(): renders configuration files, creates accounts, bootstraps its database and starts the service. Stops the run on failure.
provision/modulescreates the collector and Evocati databases, downloads DB-IP Lite for the country index, creates aegis.db and the first panel account, and starts the panel on port 9981. A failure is reported but does not abort.
build/rustinstalls the pinned Rust toolchain if needed, builds the workspace and publishes aegis-r-* into bin/. A failure does not abort.
services/keeperwrites /etc/init.d/aegis-keeper, registers it with update-rc.d, starts the keeper and waits up to 15 seconds for every registered service to be up. Stops the run on failure.
finish/platformissues a certificate for the primary domain (Let's Encrypt DNS-01 through BIND, falling back to a local one), ensures a local certificate for the primary IP and links /bin/aegis. A failure does not abort.

Inside apps/<name>, the install task removes the success stamp and writes .aegis-failed before the first file lands; verify replaces that marker with .aegis-installed, which contains the build-profile fingerprint. The plan therefore rebuilds an interrupted or failed application on the next pass, and rebuilds an application whose profile changed, while skipping one that is already complete.

#Help

#aegis thor help

Prints the same page as --help for any command in the Thor tree.

bash
aegis thor help topic ...
ArgumentDefaultMeaning
topicthe Thor command pagecommand path, for example download or runtime status

Examples:

bash
aegis thor helpaegis thor help runtime statusaegis thor help download
text
usage: aegis thor [-h] {apps,download,runtime,help} ...Download application sources and manage the bundled runtime.COMMANDS  {apps,download,runtime,help}    apps      List catalog applications    download  Download applications    runtime   Manage the bundled Python runtime    help      Show help for a commandRun 'aegis thor help <command>' for details.

The standalone launcher exposes the same tree:

bash
./bin/thor apps./bin/thor runtime status