Everything you need to install, configure, and use Aegira.
# Download
$ wget https://github.com/talatsajafa/Aegira-free-v1-releases/releases/download/v1.0.0/aegira-free-v1.0.0-x86_64.tar.gz
$ tar -xzf aegira-free-v1.0.0-x86_64.tar.gz
# Install (prompts for target)
$ sudo ./install.shRequires Linux x86_64. Docker is optional. The installer will guide you through target setup and optional email alerts.
| Command | Description |
|---|---|
| sudo aegira install | Install the Aegira service |
| sudo aegira status | Check if Aegira is running |
| sudo aegira run | Start monitoring in foreground |
| sudo aegira history | View past incidents |
| sudo aegira show-rules | List active rules (short) |
| sudo aegira rules list | List all active rules (detailed) |
| sudo aegira rules show <id> | View rule details |
| sudo aegira rules export | Export all rules as JSON |
| sudo aegira rules disable <id> | Disable a rule |
| sudo aegira rules enable <id> | Enable a disabled rule |
| sudo aegira configure service <name> | Set target systemd service |
| sudo aegira configure container <name> | Set target Docker container |
| sudo aegira configure multi <c1> <c2> ... | Set multiple target containers |
| sudo aegira configure auto <name> [--container] | Auto-configure service or container |
| sudo aegira configure alerts <on|off> [email] | Enable/disable email alerts |
| sudo aegira docker-status <name> | Inspect a container's state |
| aegira --help | Show usage |
Aegira Free allows up to 3 custom rules.
Place JSON files in /etc/aegira/rules/custom/.
/etc/aegira/rules/custom/
$ sudo nano /etc/aegira/rules/custom/my-rule.json$ sudo systemctl restart aegira.service$ sudo aegira rules list{
"id": "redis_restart",
"name": "Restart Redis on connection error",
"severity": "high",
"error_patterns": [
"redis connection failed",
"redis connection refused"
],
"context_patterns": ["redis"],
"trigger": {"type": "log"},
"remediation": {
"type": "service_restart",
"service": "redis"
},
"verification": {
"type": "service_active",
"service": "redis"
},
"action": "auto_recover",
"priority": 50
}| Field | Required | Description |
|---|---|---|
| id | Yes | Unique rule ID (lowercase, no spaces) |
| name | Yes | Human-readable name |
| severity | No | low / medium / high / critical |
| error_patterns | Yes | Log substrings that trigger the rule |
| context_patterns | No | Additional context substrings (higher match score) |
| trigger | No | log / docker_exit / docker_health / docker_oom / http_health / container_probe |
| remediation | Yes | service_restart, container_restart, command, container_exec, command_sequence, alert_only |
| verification | Yes | service_active, container_running, container_healthy, http_status, container_http_status, command_success, none |
| action | No | auto_recover / alert_only / dry_run / approval_required |
| priority | No | Higher = matched first (default 0) |
Restart a systemd service on log error:
{
"id": "nginx_restart",
"name": "Restart Nginx on connection error",
"error_patterns": ["nginx: connection refused"],
"trigger": {"type": "log"},
"remediation": {"type": "service_restart", "service": "nginx"},
"verification": {"type": "service_active", "service": "nginx"},
"action": "auto_recover",
"priority": 50
}Restart a Docker container on exit 137:
{
"id": "app_container_restart",
"name": "Restart app container on exit 137",
"error_patterns": ["exit code 137"],
"trigger": {"type": "docker_exit", "container": "my-app", "exit_codes": [137]},
"remediation": {"type": "container_restart", "container": "my-app"},
"verification": {"type": "container_running", "container": "my-app"},
"action": "auto_recover",
"priority": 50
}Heal a service inside a container without restarting it:
{
"id": "nginx_reload",
"name": "Reload nginx config inside container",
"error_patterns": ["nginx config error"],
"trigger": {"type": "log"},
"remediation": {"type": "container_exec", "container": "nginx", "args": ["nginx", "-s", "reload"]},
"verification": {"type": "container_http_status", "container": "nginx", "url": "http://127.0.0.1:8080/health", "expected_status": 200},
"action": "auto_recover",
"priority": 50
}Alert only — no automatic remediation:
{
"id": "disk_full_alert",
"name": "Alert on disk full",
"error_patterns": ["no space left on device"],
"trigger": {"type": "log"},
"remediation": {"type": "alert_only"},
"verification": {"type": "none"},
"action": "alert_only",
"priority": 50
}⚠️ Important
Rules execute as root. Destructive commands are blocked best-effort, not foolproof. Write your rules carefully.
Aegira can send Gmail alerts via Composio when incidents occur. You need a free Composio account.
During install, choose to enable alerts and provide:
app.composio.dev)Or configure later:
$ sudo aegira configure alerts on you@example.com$ sudo systemctl status aegira.service
$ sudo journalctl -u aegira -n 100
Check /var/log/aegira/incident.log for rejection reasons.
Common causes: missing error_patterns,
invalid JSON, or target not configured.
Verify your Composio API key and user ID in
/etc/aegira/composio.env.
Then check the incident log:
sudo grep -i alert /var/log/aegira/incident.log
Docker rules use TARGET_CONTAINER.
You must configure a target:
sudo aegira configure container <name>