Skip to main content

​
CLI Reference

aegis <command> [flags]

​
Commands

CommandDescription
runStart the Aegis server in the foreground
installInstall Aegis as a system service (systemd on Linux, launchd on macOS)
uninstallRemove the Aegis system service
statusShow current service status
versionPrint the version string
helpShow usage information

​
Run Flags

FlagDefaultDescription
-dbAegis.dbSQLite database file path
-admin-listen127.0.0.1:9443Admin UI bind address
-proxy-listen:80HTTP proxy bind address
-https-listen:443HTTPS proxy bind address
-debugfalseEnable debug-level logging

​
Install Flags

FlagDefaultDescription
-usercurrent userSystem user to run the service as
-working-dircurrent directoryWorking directory for the service

​
Examples

# Start with defaults
aegis run

# Debug mode with default edge listeners
aegis run -debug

# Override the HTTP proxy port for development
aegis run -proxy-listen :8080

# Custom database location
aegis run -db /var/lib/aegis/data.db

# Install as system service
sudo aegis install

# Install as a specific user
sudo aegis install -user www-data

# Remove system service
sudo aegis uninstall

# Check service status
aegis status

​
Configuration

Aegis loads configuration from three sources with the following precedence (highest wins): 
CLI flags  >  Environment variables  >  Config file  >  Defaults

​
Config File (Aegis.yml)

database_path: Aegis.db
admin_listen: 127.0.0.1:9443
proxy_listen: :80
https_listen: :443
The config file is loaded from Aegis.yml in the working directory by default, or from the path specified by the AEGIS_CONFIG environment variable.

​
Environment Variables

VariableMaps to
AEGIS_CONFIGConfig file path
AEGIS_DB_PATHdatabase_path
AEGIS_ADMIN_LISTENadmin_listen
AEGIS_PROXY_LISTENproxy_listen
AEGIS_HTTPS_LISTENHTTPS proxy bind address (default :443)
AEGIS_SSL_KEY64-char hex AES-256 key for encrypting SSL private keys at rest
AEGIS_SSL_CACHE_DIRDirectory for autocert cache (default .cache/ssl)

​
Service Management

​
Linux (systemd)

# Install
sudo aegis install

# Check status
aegis status

# Uninstall
sudo aegis uninstall

​
macOS (launchd)

# Install
sudo aegis install

# Check status
aegis status

# Uninstall
sudo aegis uninstall

​
Operations

FeatureDetails
Hot reloadAtomic pointer swap for rule chains and host config; no restart required
Structured loggingJSON output via slog
Graceful shutdownSIGINT/SIGTERM handling with 10-second drain
SQLite WAL modeConcurrent reads during writes, auto-migration on startup
SSL key encryptionAES-256-GCM at rest with auto-generated or user-provided key
Embedded frontendAdmin UI static files compiled into the binary via embed.FS