Debian 12+ systemd native Cockpit UI AgentMail API

Antigravity CLI Task Management Architecture

A lightweight, production-grade operations framework for orchestrating, monitoring, and debugging automated Antigravity CLI (agy) agent workflows on Debian Linux.

0 MB
Idle Web UI Memory (Socket Activated)
1-Click
Ad-hoc Triggering via Cockpit
Zero-MTA
Direct API Email Alerts via AgentMail
100%
Native systemd Journal Integration

End-to-End Workflow & Pipeline

Automated tasks execute inside isolated systemd cgroups with strict timeouts, logging directly to systemd-journald. Cockpit provides live stream access and manual execution buttons, while failures automatically invoke AgentMail API alerts with journal context.

flowchart LR subgraph TriggerLayer ["1. Trigger Layer"] T["📅 systemd Timers
(agy-task@*.timer)"] C["🌐 Debian Cockpit UI
(Port 9090 - Manual Run)"] end subgraph ExecLayer ["2. Execution Layer"] S["⚙️ systemd Service
(agy-task@*.service)"] L["🚀 Task Launcher
(/usr/local/bin/agy-run-task)"] A["🤖 Antigravity CLI
(agy run --file PROMPT.md)"] end subgraph ObsLayer ["3. Observability & Alerting"] J["📜 systemd-journald
(SyslogIdentifier=agy-*)"] F["🚨 OnFailure Unit
(agy-failure-notify@*.service)"] M["📬 AgentMail API
(api.agentmail.to)"] U["📧 User Inbox
(masonwan@gmail.com)"] end T -->|Scheduled Trigger| S C -->|Run Now / Start| S S --> L --> A A -->|stdout / stderr| J J -.->|Live Log View| C S -->|On Failure Trigger| F F -->|Extracts last 40 log lines| M M -->|Instant Email Alert| U classDef trigger fill:#1e293b,stroke:#3b82f6,stroke-width:1.5px,color:#f8fafc; classDef exec fill:#1e293b,stroke:#10b981,stroke-width:1.5px,color:#f8fafc; classDef alert fill:#1e293b,stroke:#f59e0b,stroke-width:1.5px,color:#f8fafc; class T,C trigger; class S,L,A exec; class J,F,M,U alert;

Debian Cockpit Web Console

Official Debian lightweight web management console that talks directly to systemd over D-Bus with zero intermediate background daemons.

⏱️

Timer Overview & Management

Inspect next scheduled trigger times, elapsed intervals, active timers, and adjust frequency without SSH.

▶️

1-Click Manual Triggers

Trigger any agent task on demand directly from the browser by clicking Run Service or Start.

📜

Live Journalctl Log Stream

Filter by service identifier (agy-%I), search agent outputs, and view ANSI colored terminal logs.

Socket Activated (Zero Idle RAM)

cockpit.socket listens on port 9090 and only spawns the web server when a connection arrives.

Install & Enable Cockpit on Debian
sudo apt update && sudo apt install -y cockpit cockpit-systemd
sudo systemctl enable --now cockpit.socket
# Access at https://<your-server-ip>:9090

Parameterized Systemd Templates

Using agy-task@.service allows you to create new scheduled tasks instantly by simply adding a prompt folder and enabling agy-task@<task-name>.timer.

/etc/systemd/system/agy-task@.service
[Unit]
Description=Antigravity CLI Task - %I
Documentation=https://antigravity.google/docs/cli/reference
After=network-online.target
Wants=network-online.target
OnFailure=agy-failure-notify@%n.service

[Service]
Type=oneshot
User=admin
Group=admin
WorkingDirectory=/home/admin/agent-workspace/%I

# Load global and task-specific environment variables
EnvironmentFile=-/etc/antigravity/env
EnvironmentFile=-/home/admin/agent-workspace/%I/.env

# Launcher wrapper script
ExecStart=/usr/local/bin/agy-run-task %I

# Runaway protection & Execution limits
TimeoutStartSec=1800
RuntimeMaxSec=3600
Restart=no

# Structured logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=agy-%I

# Resource Governance
Nice=10
MemoryMax=4G
CPUQuota=80%

[Install]
WantedBy=multi-user.target
/etc/systemd/system/agy-task@.timer
[Unit]
Description=Schedule for Antigravity CLI Task - %I

[Timer]
# Default daily schedule at 04:00 UTC (override per instance if needed)
OnCalendar=*-*-* 04:00:00
Persistent=true
RandomizedDelaySec=60

[Install]
WantedBy=timers.target
/usr/local/bin/agy-run-task
#!/usr/bin/env bash
set -euo pipefail

TASK_NAME="$1"
WORKSPACE_DIR="/home/admin/agent-workspace/${TASK_NAME}"
PROMPT_FILE="${WORKSPACE_DIR}/PROMPT.md"

if [[ ! -f "$PROMPT_FILE" ]]; then
    echo "[ERROR] Prompt file not found at ${PROMPT_FILE}" >&2
    exit 1
fi

echo "[INFO] Starting Antigravity task: ${TASK_NAME} at $(date --iso-8601=seconds)"

# Execute Antigravity CLI with the workspace prompt
exec /usr/local/bin/agy run --file "$PROMPT_FILE"

Zero-MTA API-Based Failure Alerting

When any task fails, systemd automatically triggers OnFailure=agy-failure-notify@%n.service. The script gathers the last 40 lines of journal output and sends a formatted alert email via AgentMail's REST API without requiring a local mail transfer agent (MTA).

/etc/systemd/system/agy-failure-notify@.service
[Unit]
Description=Antigravity Failure Notification Dispatcher for %I

[Service]
Type=oneshot
User=root
ExecStart=/usr/local/bin/agy-failure-notify "%I"
/usr/local/bin/agy-failure-notify
#!/usr/bin/env bash
set -euo pipefail

FAILED_UNIT="$1"
RECIPIENT="masonwan@gmail.com"
AGENTMAIL_API_KEY="${AGENTMAIL_API_KEY:-am_us_de73e963360b20c0fd390b3519b21d78c06cd8d9e37b9f64c828b7d46d18c661}"
SERVER_HOSTNAME="$(hostname -f 2>/dev/null || hostname)"
TIMESTAMP="$(date -u +"%Y-%m-%d %H:%M:%S UTC")"

# Retrieve exit status and recent journal logs for the failed unit
SYSTEMCTL_STATUS="$(systemctl status "${FAILED_UNIT}" --lines=0 --no-pager 2>&1 || true)"
RECENT_LOGS="$(journalctl -u "${FAILED_UNIT}" -n 40 --no-pager 2>&1 || true)"

SUBJECT="[ALERT] Antigravity Task Failed: ${FAILED_UNIT} on ${SERVER_HOSTNAME}"

EMAIL_BODY=$(cat <<EOF
Antigravity CLI Task Failure Report
====================================
Unit:      ${FAILED_UNIT}
Host:      ${SERVER_HOSTNAME}
Time:      ${TIMESTAMP}

Systemd Unit Status:
${SYSTEMCTL_STATUS}

Last 40 Journal Lines:
------------------------------------
${RECENT_LOGS}

------------------------------------
Inspect on Debian Cockpit: https://${SERVER_HOSTNAME}:9090/system/services#/${FAILED_UNIT}
EOF
)

# Prepare JSON payload
PAYLOAD_FILE=$(mktemp /tmp/agentmail_payload.XXXXXX.json)
python3 -c "
import json, sys
data = {
    'to': sys.argv[1],
    'subject': sys.argv[2],
    'text': sys.argv[3]
}
with open(sys.argv[4], 'w') as f:
    json.dump(data, f)
" "$RECIPIENT" "$SUBJECT" "$EMAIL_BODY" "$PAYLOAD_FILE"

# Dispatch via AgentMail API
curl -s -X POST "https://api.agentmail.to/v0/inboxes/default/messages/send" \
  -H "Authorization: Bearer ${AGENTMAIL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @"${PAYLOAD_FILE}" > /dev/null || {
    echo "[ERROR] Failed to dispatch failure email via AgentMail API" >&2
}

rm -f "${PAYLOAD_FILE}"

Directory Hierarchy & Workspace Isolation

Clean separation between global configurations, system unit files, helper binaries, and task-specific workspace trees.

/etc/
├── systemd/system/
│ ├── agy-task@.service # Universal task service template
│ ├── agy-task@.timer # Universal timer template
│ └── agy-failure-notify@.service # Failure notification unit
└── antigravity/
└── env # Global API keys & environment config
 
/usr/local/bin/
├── agy-run-task # Execution wrapper (executable)
└── agy-failure-notify # AgentMail API dispatcher (executable)
 
/home/admin/agent-workspace/
├── daily-repo-sync/
│ ├── PROMPT.md # Task instructions
│ └── .env # Task-specific env overrides
└── nightly-db-audit/
├── PROMPT.md
└── .env

Rollout & Verification Playbook

Step 1

Install & Enable Cockpit

Install the web console package and enable the socket listener.

sudo apt update && sudo apt install -y cockpit cockpit-systemd
sudo systemctl enable --now cockpit.socket
Step 2

Install Helper Scripts & Unit Templates

Place the scripts in /usr/local/bin/ and mark them executable.

sudo chmod +x /usr/local/bin/agy-run-task /usr/local/bin/agy-failure-notify
sudo systemctl daemon-reload
Step 3

Create Task Workspace & Prompt

Create the folder for your task and write its PROMPT.md.

mkdir -p /home/admin/agent-workspace/daily-repo-sync
echo "Review recent git commits and summarize changes." > /home/admin/agent-workspace/daily-repo-sync/PROMPT.md
Step 4

Enable Timer & Test Manual Run

Enable the recurring schedule and test a manual run.

# Enable daily timer
sudo systemctl enable --now agy-task@daily-repo-sync.timer

# Test manual run immediately
sudo systemctl start agy-task@daily-repo-sync.service

# View live logs
journalctl -u agy-task@daily-repo-sync -f