#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
| Path | Content |
|---|---|
config/thor/apps.json | the artifact catalog: group, name, version, URL and SHA256 |
config/thor/runtime.json | the 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/current | symlink the launchers resolve |
storage/temp/downloads | .part files while a transfer is in flight |
storage/apps/state.json | when 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.
aegis thor apps --verify| Argument / option | Default | Meaning |
|---|---|---|
--verify | off | hash 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:
aegis thor appsaegis thor apps --verifyAegis 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 stalestale 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.
aegis thor download app --force| Argument / option | Default | Meaning |
|---|---|---|
app | every catalog entry | an application name (nginx) or a full key (web/nginx-modules/geoip2) |
--force | off | download 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:
aegis thor download nginxaegis thor download web/nginx-modules/geoip2aegis thor download --forcenginx 1.30.6 [██████████████████████████████] 100%✔ web/nginx 1.30.6ℹ 1 downloaded, 0 already presentWith no argument the batch draws one timeline on stderr and finishes with:
ℹ 57 downloaded, 0 already presentUnknown names stop immediately:
✖ 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.
aegis thor runtime prepare --force| Argument / option | Default | Meaning |
|---|---|---|
--force | off | re-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:
aegis thor runtime prepareaegis thor runtime prepare --forceℹ 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.6On a prepared host:
✔ Runtime is installedbin/aegis-prepare is the same operation for a host where bin/aegis cannot run yet:
./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.
aegis thor runtime status| Argument / option | Default | Meaning |
|---|---|---|
| — | — | 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:
aegis thor runtime statusaegis thor runtime status && aegis keeper start✔ 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 readyA missing runtime stops after the first check:
✖ 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.
aegis setup --domain DOMAIN --hostname NAME --timezone ZONE --confirm| Argument / option | Default | Meaning |
|---|---|---|
--domain | existing value, or a prompt | primary domain, for example example.com |
--hostname | existing value, or the detected host name | server host name |
--timezone | existing value, or UTC | IANA timezone, for example Europe/Bucharest |
--confirm | off | accept 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:
aegis setupaegis setup --domain example.com --hostname srv1.example.com --timezone Europe/Bucharest --confirmServer 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.tomlAn invalid value stops before anything is written:
✖ 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.
aegis install app -v|--verbose|--v -y|--yes --domain DOMAIN --hostname NAME --timezone ZONE --confirm| Argument / option | Default | Meaning |
|---|---|---|
app | every application selected in server.toml | install and configure one application, plus the libraries it needs |
-v, --verbose, --v | off | detailed per-task output instead of the three-line live bar; also selected automatically when stdout is not a terminal |
-y, --yes | off | skip the setup questions and trust config/server.toml |
--domain | existing value, or a prompt | pre-answer the primary domain |
--hostname | existing value, or detected | pre-answer the host name |
--timezone | existing value, or UTC | pre-answer the IANA timezone |
--confirm | off | accept 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:
✖ 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:
aegis installaegis install nginxaegis install nginx --yes --verboseaegis install --domain example.com --timezone Europe/Bucharest --confirmA successful run ends with the closing report:
-> 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 restartAn 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.
aegis configure app -v|--verbose|--v| Argument / option | Default | Meaning |
|---|---|---|
app | every application selected in server.toml | configure only this application |
-v, --verbose, --v | off | detailed 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:
aegis configureaegis configure nginxaegis configure -vWith -v, or when stdout is not a terminal, the run prints one block per step:
⬢ 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.66sWith nothing selected there is nothing to configure:
✖ 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.
aegis build| Argument / option | Default | Meaning |
|---|---|---|
| — | — | 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:
aegis buildaegis build && aegis keeper services✔ aegis-r-bird -> /etc/aegis/bin/aegis-r-birdA missing toolchain or a compile error is reported and exits 1:
✖ 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).
| Step | Effect on the host |
|---|---|
verification/server | reads the host only: distribution support, hardware, network, outbound HTTPS, OS and kernel. Nothing is written. |
verification/vendor | reads the catalog, reports artifacts that are not downloaded yet, hashes the present ones. Nothing is written. |
core/requirements | ensures 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/toolchain | installs 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/modules | creates 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/rust | installs the pinned Rust toolchain if needed, builds the workspace and publishes aegis-r-* into bin/. A failure does not abort. |
services/keeper | writes /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/platform | issues 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.
aegis thor help topic ...| Argument | Default | Meaning |
|---|---|---|
topic | the Thor command page | command path, for example download or runtime status |
Examples:
aegis thor helpaegis thor help runtime statusaegis thor help downloadusage: 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:
./bin/thor apps./bin/thor runtime status