Vercel Deployment Watchdog

Monitor Vercel-hosted site deployments with automated health checks, cache freshness verification, and API validation. Use when you need to ensure deployment...

Security Scan

The skill's requirements and scripts are consistent with a Vercel deployment monitor; nothing in the package indicates hidden exfiltration or unrelated credential requests, but there are minor documentation inconsistencies and an opt-in flag (ALLOW_INTERNAL) that can expand network access and should be used carefully.

Purpose & Capability

Name/description (Vercel deployment monitoring) match the actual code and declared requirements: scripts call the Vercel API, inspect deployments, and perform HTTP checks. Required binaries (curl, jq) and the single required env var (VERCEL_TOKEN) are appropriate for this purpose.

Instruction Scope

SKILL.md and scripts primarily stay within monitoring scope (calling api.vercel.com, performing HTTP checks). The scripts read/write a local state file (~/.openclaw/workspace/state/watchdog-state.json by default). There is an opt-in ALLOW_INTERNAL flag that disables hostname validation and permits internal/private address checks; the README warns about it, but there is a small inconsistency in help text suggesting internal checks might be 'enabled by default' — this is a documentation mismatch to review before use.

Install Mechanism

Instruction-only with small shell scripts included; there is no remote download/extract step or package installation performed by the skill itself. Lowest-risk install mechanism.

Credentials

Only VERCEL_TOKEN is required, which is proportional to interacting with the Vercel API. Optional envs (ALLOW_INTERNAL, WATCHDOG_STATE_FILE) are reasonable for behavior tuning and state location. No unrelated credentials or high-privilege secrets are requested.

Persistence & Privilege

always:false (normal). The skill writes a local state file in the user's home workspace (default path under ~/.openclaw) — expected for tracking last deployment. The ALLOW_INTERNAL opt-in grants broader network access (internal hosts) and increases risk if misused; consider this when enabling.

Assessment

This skill appears to be what it claims: a Vercel deployment monitor that needs curl, jq and a Vercel API token. Before installing or running it: 1) Review the included scripts yourself (they are plain shell) to confirm behavior. 2) Create a Vercel token with minimal scope (deployment:read) and keep it secure; do not use a token that grants build/deploy/write access unless needed. 3) Be cautious about enabling ALLOW_INTERNAL=true — that disables hostname/private-IP checks and allows probing internal addresses, which is dangerous unless you explicitly need it and have permission. 4) Note the default state file location (~/.openclaw/...) and change WATCHDOG_STATE_FILE if you want it stored elsewhere. 5) The package source/homepage is missing; if you will run this in production, prefer code from a known repository/maintainer or verify the origin. If you want, I can scan the remainder of the truncated script parts for any additional behavior (e.g., webhooks, external upload sinks) before you run it.

Vercel Deployment Watchdog Skill

⚠️ SECURITY & USAGE DISCLAIMER

This skill is designed exclusively for monitoring your own web applications and deployments. It must not be used to probe, scan, or monitor any systems you do not own or have explicit permission to test.

Permitted Use:

• Monitoring your own websites and APIs deployed on Vercel or similar platforms
• Automated health checks for deployments you control
• Integration with your own alerting systems (Telegram, etc.)

Prohibited Use:

• Scanning third-party websites without authorization
• Attempting to access private/internal networks
• Testing systems you do not own or manage
• Any activity that could be considered unauthorized access or harassment

By using this skill, you agree to use it only for legitimate monitoring of your own infrastructure.

Skill Overview

Automated deployment monitoring for Vercel-hosted applications. This skill provides:

1. Post-deployment health checks: Verify HTTP status, cache freshness, content validation
2. Vercel API integration: Detect new deployments automatically
3. Feed validation: Check API endpoints return valid JSON with expected data
4. Cron job setup: Schedule regular checks or trigger on deployment completion
5. Alerting integration: Configure OpenClaw cron jobs to send failure notifications via Telegram/WhatsApp or webhooks (delivery handled by OpenClaw platform)

🔒 Security & Compliance

Built-in Safety Features

The skill includes multiple security measures:

1. URL Validation: All URLs are validated to:

   • Require http:// or https:// protocol
   • Warn/block localhost addresses (localhost, 127.0.0.1, 0.0.0.0)
   • Can be configured to block private IP ranges (RFC 1918)
   • Allow monitoring of internal resources via ALLOW_INTERNAL=true environment variable (requires explicit opt-in; no CLI bypass flags)
   • Security Warning: Only enable ALLOW_INTERNAL=true if you need to monitor localhost/private IPs and have explicit permission. Enabling it allows network access to internal addresses.

2. Credential Safety:

   • Never hardcodes API tokens or secrets
   • Accepts tokens via environment variables (primary) or CLI arguments
   • Scripts do not log sensitive credentials

3. Network Restrictions:

   • No outbound network calls to private IP ranges by default
   • Configurable timeout limits for HTTP requests
   • Rate limiting recommendations included

Compliance with ClawHub Policies

This skill:

• Does not attempt to bypass security controls
• Does not include obfuscated or hidden functionality
• Is open source and transparent about all operations
• Respects robots.txt and common web standards
• Follows the principle of least privilege

Responsible Usage Requirements

You must:

1. Have explicit permission to monitor all target URLs
2. Use your own API tokens with minimal required scopes
3. Respect rate limits of monitored services
4. Not use this skill for surveillance or harassment
5. Comply with all applicable laws and terms of service

Violation of these terms may result in removal from ClawHub and suspension of your account.

Quick Start

1. Prerequisites

# Check if curl and jq are installed
command -v curl >/dev/null 2>&1 && command -v jq >/dev/null 2>&1 || {
    echo "Error: curl and jq are required but not installed."
    echo "Install them using your system package manager:"
    echo "  Debian/Ubuntu: sudo apt-get install curl jq"
    echo "  macOS: brew install curl jq"
    echo "  For other systems, see: https://curl.se/ and https://stedolan.github.io/jq/"
    exit 1
}

2. Set up Environment Variables

Create a .env file or set environment variables:

# Vercel API token (create at https://vercel.com/account/tokens)
export VERCEL_TOKEN="vcp_..."

# Target URLs to monitor
export HOMEPAGE_URL="https://your-site.com/"
export API_FEED_URL="https://your-site.com/api/feed"

# Optional: Telegram chat ID for OpenClaw cron notifications (not used by scripts)
export TELEGRAM_CHAT_ID="YOUR_TELEGRAM_CHAT_ID"

# Security: Only set ALLOW_INTERNAL=true if monitoring localhost/private IPs
# export ALLOW_INTERNAL="true"

3. Run Manual Check

# Make script executable
chmod +x scripts/watchdog-check.sh

# Run check
./scripts/watchdog-check.sh --homepage "$HOMEPAGE_URL" --api "$API_FEED_URL"

4. Schedule Monitoring with OpenClaw Cron (Recommended)

For safe and integrated scheduling, use OpenClaw's built-in cron system instead of system cron:

// Create an OpenClaw cron job (every 5 minutes)
{
  "name": "Vercel Watchdog",
  "schedule": { "kind": "every", "everyMs": 300000 },
  "payload": {
    "kind": "agentTurn",
    "message": "Run deployment watchdog check for my site"
  },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "YOUR_TELEGRAM_CHAT_ID"
  }
}

See the "Integration with OpenClaw" section below for more details.

Features

Health Check Components

1. HTTP Status Verification: Ensures homepage and API return 200 OK
2. Cache Freshness: Checks age: 0 and x-vercel-cache: MISS headers
3. Content Validation: Verifies page title contains expected text
4. JSON Feed Validation: Validates API response structure and data integrity
5. Deployment Detection: Uses Vercel API to find latest deployments

Vercel API Integration

The skill can:

• List recent deployments to detect new ones
• Check deployment state (READY, ERROR, BUILDING)
• Get deployment URLs and metadata
• Trigger health checks when deployment state changes to READY

Alerting

When checks fail, the skill can:

• Send Telegram messages via OpenClaw
• Log detailed failure information
• Include remediation suggestions
• Escalate after repeated failures

Usage Examples

Basic Health Check

./scripts/watchdog-check.sh --homepage "https://your-site.com" --api "https://your-site.com/api/feed"

Vercel Deployment Monitoring

The script uses the VERCEL_TOKEN environment variable automatically, or you can pass it explicitly via --token.

# Check for new deployments in the last 10 minutes
./scripts/vercel-monitor.sh --project "your-project" --since 10m

Script Reference

scripts/watchdog-check.sh

Main health check script with the following options:

--homepage URL    # Homepage URL to check (default: https://your-site.com/)
--api URL         # API feed URL to check (default: https://your-site.com/api/feed)
--verbose         # Enable verbose output
--json            # Output results as JSON for programmatic use

scripts/vercel-monitor.sh

Vercel API integration script:

--token TOKEN     # Vercel API token (required)
--project NAME    # Project name to monitor (default: auto-detect)
--since MINUTES   # Check deployments from last N minutes (default: 5)
--team-id ID      # Team ID for organization accounts

Integration with OpenClaw

Note: This skill provides monitoring scripts that output results to stdout. Notifications are handled by OpenClaw's cron delivery system (delivery.mode: "announce") when configured, not by the scripts themselves. The scripts do not make external API calls for notifications.

As a Cron Job

Set up the skill to run periodically via OpenClaw's cron system:

// Example cron job configuration
{
  "name": "Vercel Watchdog",
  "schedule": { "kind": "every", "everyMs": 300000 }, // Every 5 minutes
  "payload": {
    "kind": "agentTurn",
    "message": "Run deployment watchdog check and notify if any failures"
  },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "YOUR_TELEGRAM_CHAT_ID"
  }
}

As a Sub-Agent

Spawn a sub-agent to handle monitoring:

# Use OpenClaw sessions_spawn to run monitoring in background
openclaw sessions spawn --task "Monitor your site deployment health for next hour" --runtime subagent --label deployment-watchdog

Troubleshooting

Common Issues

1. Vercel API authentication fails:

   • Ensure token has deployment:read scope
   • Check if token is expired (create new one at https://vercel.com/account/tokens)

2. Cache freshness indicators missing:

   • Deployment might be cached by CDN
   • Wait a few minutes and retry
   • Check Vercel project settings for cache headers

3. API feed validation fails:

   • Verify API endpoint is accessible
   • Check CORS settings if accessing from different domain
   • Validate JSON structure with jq . <(curl -s API_URL)

Debug Mode

Enable verbose output to see detailed check results:

./scripts/watchdog-check.sh --verbose

Extending the Skill

Adding New Checks

1. Add check function to scripts/watchdog-check.sh
2. Update summary output
3. Test with --verbose flag

Integrating with Other Services

• Slack notifications: Add webhook integration
• Email alerts: Use himalaya CLI or gog skill
• Dashboard integration: Output JSON for external monitoring systems

References

See references/ directory for:

• Vercel API documentation
• HTTP cache header specifications
• JSON schema validation examples
• OpenClaw cron job configuration guide