DigitalOcean Slug Grabber

A Node.js application that automatically provisions DigitalOcean Droplets when they become available. This application periodically checks for available resources and creates Droplets up to your specified count.

• DigitalOcean Slug Grabber
  • Cheat Sheet
  • Features
  • Prerequisites
  • Installation and Usage
    • Deploy to DigitalOcean App Platform as a Worker
    • Using Docker
    • Using Node.js Directly
  • Configuration Options
  • Webhook Notifications
    • For individual Droplet creation:
    • For multiple Droplets creation summary:
    • Expected console output
  • GPU Resources Cheat Sheet

Cheat Sheet

1. Use the Deploy to DO button for a ready-to-go deployment
2. doctl compute ssh-key list to get your SSH key IDs
3. For a complete list of all DigitalOcean slugs, see: slugs.do-api.dev
4. Use Discord, Slack or Webhook.site for easy Webhooks

Features

• Automatic Provisioning: Creates Droplets when they become available
• Configurable Parameters: Specify Droplet size, region, image, and count
• Smart Provisioning: Only creates new Droplets if your desired count isn't reached (recognized by tag)
• Multi-Region Failover: With multiple regions, tries each in order until the desired count is met
• Docker Support: Run as a containerized application
• Webhook Notifications: Get notified via webhook when Droplets are created

Prerequisites

• DigitalOcean API Token with write access
• Node.js 22+ (for direct Node.js usage)
• Docker (for container usage)

Installation and Usage

Deploy to DigitalOcean App Platform as a Worker

spec:
  name: do-slug-grabber
  region: lon
  workers:
  - dockerfile_path: /Dockerfile
    envs:
    - key: DO_API_TOKEN
      scope: RUN_TIME
      type: SECRET
      value: 
    - key: SLUG
      scope: RUN_TIME
      value: s-1vcpu-1gb
    - key: REGION
      scope: RUN_TIME
      value: tor1  # or multiple: tor1,nyc1,sfo3
    - key: IMAGE
      scope: RUN_TIME
      value: debian-12-x64
    - key: DESIRED_COUNT
      scope: RUN_TIME
      value: "1"
    - key: SSH_KEYS
      scope: RUN_TIME
      value: "<id>" # doctl compute ssh-key list
    - key: WEBHOOK_URL
      scope: RUN_TIME
      value: https://webhook.site/<your-webhook-id>
    - key: NAME_PREFIX
      scope: RUN_TIME
      value: my-droplet  # Optional: custom prefix for droplet names
    git:
      branch: main
      deploy_on_push: true
      repo_clone_url: https://github.com/DO-Solutions/slug-grabber.git
    instance_count: 1
    instance_size_slug: apps-s-1vcpu-0.5gb
    name: slug-grabber
    source_dir: /

Using Docker

Details

1. Build the Docker image:

   docker build -t do-grabber .

2. Run the container with your configuration:

   docker run -d \
     -e DO_API_TOKEN="your-do-api-token" \
     -e SLUG="gpu-h100x8-640gb" \
     -e REGION="tor1" \
     -e IMAGE="gpu-h100x8-base" \
     -e DESIRED_COUNT="1" \
     -e SSH_KEYS="123456,789012" \
     -e WEBHOOK_URL="https://your-webhook-url" \
     -e NAME_PREFIX="my-droplet" \
     --name do-h100-grabber \
     do-grabber

Using Node.js Directly

Details

1. Clone the repository:

   git clone https://github.com/do-solutions/slug-grabber.git
   cd slug-grabber

2. Install dependencies:

   npm install

3. Run the application with your configuration:

   DO_API_TOKEN="your-do-api-token" WEBHOOK_URL="https://your-webhook-url" NAME_PREFIX="my-droplet" npm start -- \
     --slug="gpu-h100x8-640gb" \
     --region="tor1" \
     --image="gpu-h100x8-base" \
     --desired_count=1 \
     --ssh_keys="123456,789012"
   
   # Multiple regions (tries tor1 first, falls back to nyc1 if unavailable):
   npm start -- --slug="gpu-h100x8-640gb" --region="tor1,nyc1" --image="gpu-h100x8-base" --desired_count=1

   You can also specify the webhook URL as a command line parameter:

   DO_API_TOKEN="your-do-api-token" NAME_PREFIX="my-droplet" npm start -- \
     --slug="gpu-h100x8-640gb" \
     --region="tor1" \
     --image="gpu-h100x8-base" \
     --desired_count=1 \
     --ssh_keys="123456,789012" \
     --webhook_url="https://your-webhook-url"

Configuration Options

Parameter	Description	Example
slug	The size/type of GPU Droplet	gpu-h100x8-640gb
region	Region(s) where Droplets will be created — comma-separated for multiple	tor1 or tor1,nyc1,sfo3
image	The OS image to use	gpu-h100x8-base
desired_count	Number of Droplets to maintain globally across all listed regions	1
ssh_keys	Comma-separated list of SSH key IDs to add	123456,789012
webhook_url	(Optional) URL to send notifications when Droplets are created	https://hooks.slack.com/services/XXX/YYY/ZZZ
NAME_PREFIX	(Optional) Custom prefix for Droplet names. If not set, uses the slug as prefix	my-droplet

Note: Droplet names follow the pattern {prefix}-{region}-{index} (e.g., my-droplet-tor1-1, my-droplet-nyc1-1). By default, the prefix is the slug; set NAME_PREFIX to use a custom prefix. With multiple regions, desired_count is the global total — the app checks all listed regions for existing tagged droplets and only creates new ones until the count is met (e.g. REGION=tor1,nyc1 and desired_count=1 creates 1 droplet total, trying tor1 first then nyc1 if needed).

Droplet Recognition: Existing droplets are identified by their tag (matching the slug), not by size slug. This means droplets created outside the tool will be counted as long as they are tagged with the slug value. New droplets created by the tool are automatically tagged.

Webhook Notifications

When a Droplet is successfully created, the application will send a webhook notification to the specified URL. The notification is a JSON payload with the following structure:

For individual Droplet creation:

Details

{
  "event": "droplet_created",
  "droplet": {
    "id": 123456789,
    "name": "gpu-h100x8-640gb-1",
    "region": "tor1",
    "size_slug": "gpu-h100x8-640gb",
    "image": "gpu-h100x8-base",
    ...
  },
  "timestamp": "2023-11-06T12:34:56.789Z",
  "configuration": {
    "slug": "gpu-h100x8-640gb",
    "region": "tor1",
    "image": "gpu-h100x8-base"
  }
}

With multiple regions, droplet names include the region (e.g. my-droplet-tor1-1, my-droplet-nyc1-1).

For multiple Droplets creation summary:

Details

{
  "event": "droplets_created_summary",
  "createdCount": 2,
  "existingCount": 0,
  "dropletIds": [123456789, 987654321],
  "timestamp": "2023-11-06T12:34:56.789Z",
  "configuration": {
    "slug": "gpu-h100x8-640gb",
    "region": "tor1",
    "image": "gpu-h100x8-base"
  }
}

Expected console output

Details

DigitalOcean Slug Grabber Node.js started
Configuration: slug=s-1vcpu-1gb, regions=tor1, image=debian-12-x64, desired_count=1 (global across regions)
Webhook notifications enabled: https://webhook.site/3345c481-c248-4956-9361-335a0d1abcc8
Checking for s-1vcpu-1gb droplets across regions: tor1...
Found 0 existing droplet(s) tagged "s-1vcpu-1gb" across listed regions. Desired count: 1
Need to create 1 new droplet(s). Trying regions in order: tor1...
Attempting to create droplet "s-1vcpu-1gb-tor1-1" in tor1...
Created droplet: s-1vcpu-1gb-tor1-1 (ID: 491276154) in tor1
Sending webhook notification to https://webhook.site/3345c481-c248-4956-9361-335a0d1abcc8
Webhook notification sent successfully
Successfully created 1 new droplet(s) across regions.
Checking for s-1vcpu-1gb droplets across regions: tor1...
Found 1 existing droplet(s) tagged "s-1vcpu-1gb" across listed regions. Desired count: 1
No new droplets needed. Current count: 1, desired: 1

You can use these webhooks to integrate with services like Slack, Discord, or your own applications.

GPU Resources Cheat Sheet

GPU Type	Slug	Image	Description
NVIDIA L40S	gpu-l40sx1-48gb	-	1 L40S GPU, 48GB VRAM
NVIDIA H100	gpu-h100x1-80gb	gpu-h100x1-base	1 H100 GPU, 80GB VRAM
NVIDIA H100	gpu-h100x8-640gb	gpu-h100x8-base	8 H100 GPUs with NVLink, 640GB total VRAM

For a complete list of all DigitalOcean slugs, see: slugs.do-api.dev