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.
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.
(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.
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.
[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
[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/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).
[Unit]
Description=Antigravity Failure Notification Dispatcher for %I
[Service]
Type=oneshot
User=root
ExecStart=/usr/local/bin/agy-failure-notify "%I"
#!/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.
Rollout & Verification Playbook
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
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
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
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