#web-admin
aegis web-admin runs the Aegis panel: a FastAPI application served by uvicorn. It is not supervised by the keeper; start detaches one process, and status trusts the pid file only while that process is alive. aegis restart still stops the panel first and starts it last, so it never answers requests while the other services are half-restarted.
aegis web-admin setup # configuration, dependencies, aegis.db, first accountaegis web-admin start # start in the backgroundaegis web-admin stopaegis web-admin restartaegis web-admin run # foreground; this is what start launchesaegis web-admin statusaegis web-admin passwd # change a panel account passwordDefaults come from config/web_admin.toml: web_admin.host is 0.0.0.0 and web_admin.port is 9981. Flags win over the file; the file wins over the defaults.
| path | content |
|---|---|
/aegis/run/web-admin.pid | pid of the running panel, written by run |
/aegis/logs/web-admin.log | stdout and stderr of the background process |
/aegis/database/storage/aegis/aegis.db | accounts, sessions and settings |
/aegis/config/web_admin.toml | host, port, session TTL, cookie name, assets |
Output is human-formatted; the group does not consult the global --json flag. Exit codes are 0 for a completed command, 1 for a reported failure and 2 for an argparse error.
#Commands
#aegis web-admin setup
Prepares everything the panel needs on a host, then prints one line per step. It is idempotent: dependencies already importable are not installed again, the database is migrated only when needed, and the first account is created only while the users table is empty.
aegis web-admin setup --name=<display> --username=<login> --email=<address> --password=<secret> --non-interactive| argument | default | meaning |
|---|---|---|
--name | the username | display name of the first account |
--username | empty | login name; prompted for when omitted |
--email | empty | address of the first account |
--password | empty | prompted twice when omitted |
--non-interactive | off | refuse to prompt; --username and --password become required |
What it does, in order:
/aegis/config/web_admin.toml exists — a missing file is anerror, not something the command writes;
fastapi, uvicorn, jinja2, python-multipart and tomlkit. Ifany is missing, it runs pip install for the pinned versions: fastapi==0.163.1, uvicorn==0.54.0, jinja2==3.1.6, python-multipart==0.0.33, tomlkit==0.15.2;
aegis.db and applies the migrations underdatabase/migrations/core/aegis;
prompts;
aegis web-admin setupaegis web-admin setup --username=admin --password='s3cret' --name='Platform Admin' --email=ops@example.com --non-interactiveFresh host:
✔ configuration: /aegis/config/web_admin.toml✔ dependencies: fastapi 0.163.1, uvicorn 0.54.0, jinja2 3.1.6, python-multipart 0.0.33, tomlkit 0.15.2✔ /aegis/database/storage/aegis/aegis.db (0001_init.sql, 0002_cron.sql, 0003_cron_orphans.sql applied)✔ created account admin (id 1)✔ panel on http://0.0.0.0:9981Second run:
✔ configuration: /aegis/config/web_admin.toml✔ dependencies: fastapi 0.163.1, uvicorn 0.54.0, jinja2 3.1.6, python-multipart 0.0.33, tomlkit 0.15.2✔ /aegis/database/storage/aegis/aegis.db (up to date)✔ accounts: 1 already present✔ panel on http://0.0.0.0:9981When dependencies had to be installed, step 2 reads dependencies installed: … instead. With --non-interactive and no --username/--password it stops with ✖ --username and --password are required, exit 1. The prompts are Name:, Username:, Email: and Password:; the password is read twice, and a mismatch aborts with ✖ passwords do not match.
#aegis web-admin start
Starts the panel in its own session, writes the pid file and waits up to 20 seconds for it to appear. Logs go to /aegis/logs/web-admin.log.
aegis web-admin start --host=<address> --port=<number>| argument | default | meaning |
|---|---|---|
--host | web_admin.host | address to bind; 0.0.0.0 when the file says nothing |
--port | web_admin.port | port to bind; 9981 when the file says nothing; 0 means "use the file" |
aegis web-admin startaegis web-admin start --host=127.0.0.1 --port=8443✔ started (pid 48122) on 127.0.0.1:8443With no flags the line names the configured values, 0.0.0.0:9981 by default.
Other outcomes, all printed as a success line with exit 0:
✔ already running (pid 48122)✔ exited immediately, see /aegis/logs/web-admin.log✔ started (pid 48122), still initialising, see /aegis/logs/web-admin.logexited immediately means the child died before writing its pid file; the log holds the reason. A missing dependency gets a hint, and any other exception ends the command with exit 1:
✖ No module named 'uvicorn'; run `aegis web-admin setup` first#aegis web-admin stop
Asks the panel to exit with SIGTERM and waits up to 15 seconds for the pid file to disappear. A stale pid file is removed rather than reported.
aegis web-admin stop| argument | default | meaning |
|---|---|---|
--host, --port | — | accepted for symmetry with start and ignored by this command |
aegis web-admin stopaegis web-admin stop # a second call reports that nothing runs✔ stopped (pid 48122)✔ not runningIf the process ignores the signal:
✔ pid 48122 did not stop within 15s; check /aegis/logs/web-admin.logThat line is a message, not a failure: the exit code is still 0.
#aegis web-admin restart
Runs stop, then start, and prints both results in order.
aegis web-admin restart --host=<address> --port=<number>| argument | default | meaning |
|---|---|---|
--host | web_admin.host | address for the new process |
--port | web_admin.port | port for the new process; 0 means "use the file" |
aegis web-admin restartaegis web-admin restart --port=8080✔ stopped (pid 48122)✔ started (pid 48210) on 0.0.0.0:8080When nothing was running, the first line is ✔ not running and the second still starts the panel.
#aegis web-admin run
Runs uvicorn in the foreground. This is the command start launches in the background, with the same host and port; the child writes the pid file itself and removes it on exit.
aegis web-admin run --host=<address> --port=<number>| argument | default | meaning |
|---|---|---|
--host | web_admin.host | address to bind |
--port | web_admin.port | port to bind; 0 means "use the file" |
aegis web-admin runaegis web-admin run --host=127.0.0.1 --port=9982The output is uvicorn's own log, which is also what lands in /aegis/logs/web-admin.log when start runs it:
INFO: Uvicorn running on http://0.0.0.0:9981 (Press CTRL+C to quit)Ctrl+C stops the server; the finally block removes the pid file and the process exits 0. Requests are logged (access_log=True), and X-Forwarded-Proto is trusted only from web_admin.forwarded_allow_ips (default 127.0.0.1), which is what marks the session cookie Secure behind a TLS-terminating proxy.
#aegis web-admin status
Prints where the panel listens and what it has stored. It takes no options; the address comes from web_admin.toml and the defaults.
aegis web-admin status| argument | default | meaning |
|---|---|---|
| — | — | the command takes no options |
aegis web-admin statusaegis web-admin status # what to check before a deployRunning:
ℹ Web admin state running (pid 48122), up 3h 12m address 0.0.0.0:9981 log /aegis/logs/web-admin.log database /aegis/database/storage/aegis/aegis.db (212.0 KiB) tables schema_migrations, sessions, settings, users accounts 1 sessions 2 dependencies ok: fastapi 0.163.1, uvicorn 0.54.0, jinja2 3.1.6, python-multipart 0.0.33, tomlkit 0.15.2Stopped:
ℹ Web admin state stopped address 0.0.0.0:9981 log /aegis/logs/web-admin.log database /aegis/database/storage/aegis/aegis.db (212.0 KiB) tables schema_migrations, sessions, settings, users accounts 1 sessions 0 dependencies ok: fastapi 0.163.1, uvicorn 0.54.0, jinja2 3.1.6, python-multipart 0.0.33, tomlkit 0.15.2ℹ start it with `aegis web-admin start`state is running (pid N), up <time> or stopped; uptime is read from /proc. database shows the file size in binary units. tables lists what exists in aegis.db, or none. dependencies is ok: <versions> or incomplete: missing: <names>.
#aegis web-admin passwd
Changes the password of one panel account and closes every session of it.
aegis web-admin passwd <username>| argument | default | meaning |
|---|---|---|
<username> | admin | the panel account to update |
aegis web-admin passwdaegis web-admin passwd opsThe password is read twice without echo; an empty answer aborts, and three mismatches in a row abort with a message:
New password: Repeat password: ✔ password changed for admin; sessions closed✖ empty password; nothing changed⚠ passwords do not match, try againFailures exit 1 and change nothing: no such account: ops, cannot read the accounts: no such table: users. Every session row of that account is deleted, so a browser holding the old cookie is logged out on its next request.