Aegis documentation

#The CLI Book

aegis is the command line of the Aegis hosting platform: one program with subcommands for everything the platform does. It installs applications, builds their sources, supervises their daemons, creates mail domains, issues certificates, and renders this manual. The panel performs most of its writes through the same code, so what you type and what the panel does cannot drift apart.

This book is the reference for that command line. Each command page covers one group; every command on it has a description, its syntax, a table of the options and their defaults, copy-paste examples, and the output the command prints. It is written for an operator who knows Linux but not this codebase: no knowledge of the Python modules is assumed.

#Running a command

bash
./bin/aegis status             # from a checkout/bin/aegis status              # installed host: the link the installer madeaegis --json status            # global options go before the command

bin/aegis resolves its own location, including through a symlink, changes to the project root, and runs the bundled interpreter at runtime/python/current/bin/python3 with -E -s. The host's PYTHONPATH and user site-packages therefore cannot change what a command sees. If the runtime is missing the launcher says so and exits 1; bin/aegis thor runtime prepare builds it.

Commands that install, configure or change permissions work on the host itself and are meant to run as root. Read the page of a command before running it as another account.

#How the commands are organised

LayerSpellingExamples
install phasesaegis <command>install, setup, configure, build
reportsaegis <command>status, check, restart
module groupsaegis <group> <action>aegis keeper restart
cubesaegis cubes <app> <action>aegis cubes nginx reload

A group is a module with its own set of actions; a cube is one installed application (nginx, php, postfix, …) reached through aegis cubes. Cube actions are mounted from the cube's own directory, so --help on a cube lists exactly what that application supports.

Groups built on the shared group helper print their own command list when called without an action: aegis ai, aegis cubes nginx config. Every cube also answers help with its commands and examples, and aegis cubes help does the same for all of them. Groups built on plain subparsers (sys, docs, tasker, or a cube itself) require an action and answer a usage error with exit code 2; use --help there.

#How to read a page

Every command entry has the same parts:

  • one line saying what the command is for;
  • a syntax block, with optional parts in square brackets;
  • an options table: the flag, its default, and what it changes;
  • at least two examples — one minimal, one the way it is used in practice;
  • a fenced block with real output, so you know what success looks like.
  • Commands or options that change the host irreversibly are marked Destructive. in bold. Nothing else on a page is a warning of that weight.

    The rules that hold for every command — global options, JSON payloads, exit codes, streams, colour and the task model — are on Conventions and are not repeated on each page.

    #How aegis --help maps onto the book

    aegis with no arguments prints the command list and exits 0, and the same page answers aegis help, aegis -h and aegis help <command>. The order is the one the parser mounts, which follows the work: what a new host runs first, then daily operation, the hosting surface and the platform below.

    text
    aegis  Hosting platform controlCommands  install    Prepare the host: setup questions, checks and builds  setup      Ask the install questions and write server.toml  build      Compile and publish the Rust applications  configure  Write application configuration and start the services  status     Keeper, services and scheduled jobs at a glance  check      Health check, with the command that fixes each problem  restart    Restart the keeper, the supervised services and the panel  account    Create, inspect and retire hosting accounts  web        nginx vhosts, PHP configuration and the web database  db         Databases, migrations and seeders  ssl        Local certificates for the services  geoip      Download and inspect MaxMind databases  keeper     Supervise the platform daemons  collector  Collect and store platform counters  pulse      Realtime monitor feeding the WebSocket transport  tasker     Run and inspect tasks  cubes      Configure and reload the installed applications  thor       Application sources and the bundled Python runtime  ai         AI providers, models, agents and chats  sys        File permissions for accounts and the web user  web-admin  Run and inspect the Aegis panel  docs       Build the HTML documentation, or serve it  create     Pack this checkout into an installable archive  publish    Link the launcher so `aegis` works everywhereRun 'aegis <command> --help' for the options of one command.

    #Building an installer

    aegis create packs this checkout into one archive a fresh host can unpack: the code, the bundled runtime, the migrations and the shipped configuration. It writes storage/app/install/aegis-<major>-<minor>.tar.gz and keeps only that file — the previous archive is removed.

    The version is a counter, not a date: the minor goes 1..30, then the major steps and the minor starts again at 01 (1-30 is followed by 2-01). The counter lives in storage/app/install/version.json, next to the archive it named, so it survives the file being replaced.

    bash
    aegis createaegis --json create
    console
     aegis create aegis 1.02  187.2 MB  /etc/aegis/storage/app/install/aegis-1-02.tar.gz

    The installer page is not a server of its own: the panel serves it at /installer, together with /docs. That page has no authentication on purpose — a fresh host has no account yet, and the whole point is copying one command from another machine.

    routeserves
    /installerthe instructions, with the install line to copy
    /installer/installthe bash installer from the checkout root
    /installer/download/<file>one archive, by file name
    /installer/files.jsonthe archive list

    The browser address becomes the host a remote machine downloads from, so open the page on the address that machine can reach.

    The host pipes the script into bash. The panel fills the download address into it at serve time, so no argument is needed — the archive comes from the same host the script came from. The script extracts into /etc/aegis and stops there, printing the command that continues in a real terminal:

    bash
    cd /etc/aegis; ./bin/aegis install

    It does not start the install by itself: a script piped from the network has no reliable stdin, and the setup asks questions.

    #Linking the launcher

    The installer links the launcher once, as its bin-link task, so a host that ran the full install answers to aegis from any directory. After a reinstall, or on a host where the link was removed, publish creates it again:

    bash
    aegis publish                     # /bin/aegis -> <checkout>/bin/aegisaegis publish --path /usr/local/bin/aegisaegis --json publish

    It is idempotent: a link that already points at this checkout is reported and nothing is written. A file or link pointing somewhere else is never replaced — the command refuses and exits 1.

    console
     aegis publish /bin/aegis -> /etc/aegis/bin/aegis

    --help on a command or group prints its usage line, its options and argparse's help text for each one (the per-account verbs under account are the exception: they build their own parsers). That is enough to recall a flag; it is not enough to know what the flag changes, what the command prints, or which exit code it returns. The book adds exactly those:

    What you needWhere to find it
    the command listaegis, or the contents below
    flags and defaultsaegis <command> --help and its options table
    what a flag changesthe options table and the mode tables on its page
    what it printsthe output blocks on its page
    what a script may rely onConventions

    Two habits keep the line unambiguous: put global options before the command (aegis --json status), and put an action before its options (aegis sys perms --path /srv/site --check).

    #Contents

    #Start here

  • The CLI Book — this page.
  • Conventions — global options, JSON, exit codes, streams,
  • colour, live lines, the task model.

  • sys — host-level operations: permissions on a tree.
  • docs — build the HTML manual, preview it locally.
  • #Install and operate

  • thor — catalog, artifact downloads, bundled runtime.
  • keeper — the supervisor and the services it restarts.
  • tasker — the task queue, its daemon and its history.
  • db — the panel's SQLite databases, migrations and seeders.
  • #The platform

  • account — hosting accounts, sites, SSH keys, cron, quotas.
  • web — nginx vhosts and PHP versions.
  • web-admin — run the panel itself.
  • ssl — certificates for services.
  • #Intelligence

  • ai — providers, models, agents and chats.
  • collector — collect and store platform counters.
  • pulse — the realtime feed behind the panel's live data.
  • geoip — MaxMind databases.
  • bird — the message bus the daemons publish on.
  • #Cubes

    One page per application: nginx, php, bind, certbot, mail, postfix, dovecot, opendkim, postsrsd, postgresql, mariadb, redis, beanstalkd, vsftpd, supervisor, and composer, git, ffmpeg.

    The root-level commands (install, setup, configure, build, status, check, restart) are a sequence rather than a group; the manual's Command line page is the short reference for them.

    #Where the book lives

    The sources are docs/cli-book/*.md. The sidebar order is written by hand in app/modules/docs/book.py, one Page per document, because the order a reader follows is not the order of the file names. aegis docs build renders the book as its own site under public/docs/cli-book/, and an installed panel serves it at /docs/cli-book/. A page whose source file is missing is skipped by the builder rather than rendered empty.