claffin · claffin · Aug 14, 2025 · Aug 14, 2025 · Aug 14, 2025
diff --git a/.env.example b/.env.example
@@ -0,0 +1,163 @@
+# CloudProxy Environment Configuration Example
+# Copy this file to .env and fill in your values
+
+# ====================
+# Authentication Settings
+# ====================
+# Required: Set credentials for proxy authentication (alphanumeric only)
+PROXY_USERNAME=changeme
+PROXY_PASSWORD=changeme
+
+# Optional: Restrict access to host IP only
+# ONLY_HOST_IP=False
+
+# Optional: Proxy age limit in seconds (0 = disabled)
+# AGE_LIMIT=0
+
+# ====================
+# DigitalOcean Provider
+# ====================
+# Enable provider
+DIGITALOCEAN_ENABLED=False
+
+# Required if enabled
+DIGITALOCEAN_ACCESS_TOKEN=your_digitalocean_token_here
+
+# Optional settings
+# DIGITALOCEAN_REGION=lon1
+# DIGITALOCEAN_MIN_SCALING=2
+# DIGITALOCEAN_MAX_SCALING=2
+# DIGITALOCEAN_SIZE=s-1vcpu-1gb
+
+# Additional DigitalOcean instance example
+# DIGITALOCEAN_NYC_ENABLED=False
+# DIGITALOCEAN_NYC_ACCESS_TOKEN=your_second_token_here
+# DIGITALOCEAN_NYC_REGION=nyc1
+# DIGITALOCEAN_NYC_MIN_SCALING=3
+# DIGITALOCEAN_NYC_SIZE=s-1vcpu-1gb
+# DIGITALOCEAN_NYC_DISPLAY_NAME=NYC Proxies
+
+# ====================
+# AWS Provider
+# ====================
+# Enable provider
+AWS_ENABLED=False
+
+# Required if enabled
+AWS_ACCESS_KEY_ID=your_aws_access_key_here
+AWS_SECRET_ACCESS_KEY=your_aws_secret_key_here
+
+# Optional settings
+# AWS_REGION=eu-west-2
+# AWS_MIN_SCALING=2
+# AWS_MAX_SCALING=2
+# AWS_SIZE=t2.micro
+# AWS_AMI=ami-096cb92bb3580c759
+# AWS_SPOT=False
+
+# Additional AWS instance example
+# AWS_USEAST_ENABLED=False
+# AWS_USEAST_ACCESS_KEY_ID=your_second_key_here
+# AWS_USEAST_SECRET_ACCESS_KEY=your_second_secret_here
+# AWS_USEAST_REGION=us-east-1
+# AWS_USEAST_MIN_SCALING=2
+# AWS_USEAST_AMI=ami-0c02fb55731490381
+# AWS_USEAST_DISPLAY_NAME=US East Proxies
+
+# ====================
+# Google Cloud Provider
+# ====================
+# Enable provider
+GCP_ENABLED=False
+
+# Required if enabled
+GCP_PROJECT=your_gcp_project_id_here
+GCP_SERVICE_ACCOUNT_KEY=your_service_account_json_here
+
+# Optional: Use a JSON file instead
+# GCP_SA_JSON=/path/to/service-account.json
+
+# Optional settings
+# GCP_ZONE=us-central1-a
+# GCP_MIN_SCALING=2
+# GCP_MAX_SCALING=2
+# GCP_SIZE=f1-micro
+# GCP_IMAGE_PROJECT=ubuntu-os-cloud
+# GCP_IMAGE_FAMILY=ubuntu-minimal-2004-lts
+
+# Additional GCP instance example
+# GCP_EUROPE_ENABLED=False
+# GCP_EUROPE_PROJECT=your_project_id_here
+# GCP_EUROPE_SERVICE_ACCOUNT_KEY=your_key_here
+# GCP_EUROPE_ZONE=europe-west1-b
+# GCP_EUROPE_MIN_SCALING=2
+# GCP_EUROPE_DISPLAY_NAME=Europe Proxies
+
+# ====================
+# Hetzner Provider
+# ====================
+# Enable provider
+HETZNER_ENABLED=False
+
+# Required if enabled
+HETZNER_ACCESS_TOKEN=your_hetzner_token_here
+
+# Optional settings
+# HETZNER_LOCATION=nbg1
+# HETZNER_MIN_SCALING=2
+# HETZNER_MAX_SCALING=2
+# HETZNER_SIZE=cx21
+
+# Additional Hetzner instance example
+# HETZNER_US_ENABLED=False
+# HETZNER_US_ACCESS_TOKEN=your_second_token_here
+# HETZNER_US_LOCATION=ash
+# HETZNER_US_MIN_SCALING=2
+# HETZNER_US_SIZE=cx21
+# HETZNER_US_DISPLAY_NAME=US Proxies
+
+# ====================
+# Vultr Provider
+# ====================
+# Enable provider
+VULTR_ENABLED=False
+
+# Required if enabled
+VULTR_API_TOKEN=your_vultr_api_token_here
+
+# Optional settings
+# VULTR_REGION=ewr
+# VULTR_MIN_SCALING=2
+# VULTR_MAX_SCALING=2
+# VULTR_PLAN=vc2-1c-1gb
+# VULTR_OS_ID=387
+
+# Additional Vultr instance example
+# VULTR_EUROPE_ENABLED=False
+# VULTR_EUROPE_API_TOKEN=your_second_token_here
+# VULTR_EUROPE_REGION=ams
+# VULTR_EUROPE_MIN_SCALING=3
+# VULTR_EUROPE_PLAN=vc2-1c-1gb
+# VULTR_EUROPE_DISPLAY_NAME=Europe Proxies
+
+# Additional Vultr instance for Asia
+# VULTR_ASIA_ENABLED=False
+# VULTR_ASIA_API_TOKEN=your_third_token_here
+# VULTR_ASIA_REGION=sgp
+# VULTR_ASIA_MIN_SCALING=2
+# VULTR_ASIA_PLAN=vc2-1c-2gb
+# VULTR_ASIA_DISPLAY_NAME=Asia Proxies
+
+# ====================
+# Azure Provider (Planned)
+# ====================
+# AZURE_ENABLED=False
+# AZURE_SUBSCRIPTION_ID=your_subscription_id_here
+# AZURE_CLIENT_ID=your_client_id_here
+# AZURE_CLIENT_SECRET=your_client_secret_here
+# AZURE_TENANT_ID=your_tenant_id_here
+# AZURE_RESOURCE_GROUP=cloudproxy-rg
+# AZURE_LOCATION=eastus
+# AZURE_MIN_SCALING=2
+# AZURE_MAX_SCALING=2
+# AZURE_SIZE=Standard_B1s
diff --git a/.gitignore b/.gitignore
@@ -153,3 +153,4 @@ pnpm-debug.log*
 *.sln
 *.sw?
 .cursor-project-context
+CLAUDE.md
diff --git a/README.md b/README.md
@@ -72,11 +72,11 @@ CloudProxy exposes an API and modern UI for managing your proxy infrastructure.
 * [AWS](docs/aws.md)
 * [Google Cloud](docs/gcp.md)
 * [Hetzner](docs/hetzner.md)
+* [Vultr](docs/vultr.md)
 
 ### Planned:
 * Azure
 * Scaleway
-* Vultr
 
 ### Features:
 * **Docker-first deployment** - Simple, isolated, production-ready
@@ -348,10 +348,15 @@ curl -X 'GET' 'http://localhost:8000/' -H 'accept: application/json'
 
 #### Set target proxy count
 ```bash
-# CloudProxy will maintain exactly 5 proxies
+# CloudProxy will maintain exactly 5 proxies (DigitalOcean)
 curl -X 'PATCH' 'http://localhost:8000/providers/digitalocean' \
   -H 'Content-Type: application/json' \
   -d '{"min_scaling": 5, "max_scaling": 5}'
+
+# Or for Vultr
+curl -X 'PATCH' 'http://localhost:8000/providers/vultr' \
+  -H 'Content-Type: application/json' \
+  -d '{"min_scaling": 3, "max_scaling": 3}'
 ```
 
 ### Python Usage Example
@@ -433,6 +438,7 @@ Project Link: [https://github.com/claffin/cloudproxy](https://github.com/claffin
 - **GCP**: Check that the service account has necessary permissions
 - **DigitalOcean**: Verify the access token has write permissions
 - **Hetzner**: Ensure the API token is valid
+- **Vultr**: Verify the API token has appropriate permissions and the selected plan/region is available
 
 #### Docker container issues
 ```bash

diff --git a/cloudproxy-ui/src/components/ListProxies.vue b/cloudproxy-ui/src/components/ListProxies.vue
@@ -247,7 +247,8 @@ export default {
         'aws': 'AWS',
         'gcp': 'GCP',
         'hetzner': 'Hetzner',
-        'azure': 'Azure'
+        'azure': 'Azure',
+        'vultr': 'Vultr'
       };
 
       const providerName = specialCases[name] || name.charAt(0).toUpperCase() + name.slice(1);
@@ -265,7 +266,8 @@ export default {
         aws: 'cloud-fill',
         gcp: 'google',
         hetzner: 'hdd-rack',
-        azure: 'microsoft'
+        azure: 'microsoft',
+        vultr: 'server'
       };
       return icons[provider] || 'cloud-fill';
     };

diff --git a/cloudproxy/main.py b/cloudproxy/main.py
@@ -342,14 +342,16 @@ class ProviderInstance(BaseModel):
     enabled: bool
     ips: List[str] = []
     scaling: ProviderScaling
-    size: str
+    size: Optional[str] = None  # Made optional, some providers use different naming
+    plan: Optional[str] = None  # For Vultr provider
     region: Optional[str] = None
     location: Optional[str] = None
     datacenter: Optional[str] = None
     zone: Optional[str] = None
     image_project: Optional[str] = None
     image_family: Optional[str] = None
     ami: Optional[str] = None
+    os_id: Optional[int] = None  # For Vultr provider
     spot: Optional[bool] = None
     display_name: Optional[str] = None
     project: Optional[str] = None

diff --git a/cloudproxy/providers/manager.py b/cloudproxy/providers/manager.py
@@ -5,6 +5,7 @@
 from cloudproxy.providers.gcp.main import gcp_start
 from cloudproxy.providers.digitalocean.main import do_start
 from cloudproxy.providers.hetzner.main import hetzner_start
+from cloudproxy.providers.vultr.main import vultr_start
 
 
 def do_manager(instance_name="default"):
@@ -47,6 +48,16 @@ def hetzner_manager(instance_name="default"):
     return ip_list
 
 
+def vultr_manager(instance_name="default"):
+    """
+    Vultr manager function for a specific instance.
+    """
+    instance_config = settings.config["providers"]["vultr"]["instances"][instance_name]
+    ip_list = vultr_start(instance_config)
+    settings.config["providers"]["vultr"]["instances"][instance_name]["ips"] = [ip for ip in ip_list]
+    return ip_list
+
+
 def init_schedule():
     sched = BackgroundScheduler()
     sched.start()
@@ -57,6 +68,7 @@ def init_schedule():
         "aws": aws_manager,
         "gcp": gcp_manager,
         "hetzner": hetzner_manager,
+        "vultr": vultr_manager,
     }
 
     # Schedule jobs for all provider instances

diff --git a/cloudproxy/providers/settings.py b/cloudproxy/providers/settings.py
@@ -84,6 +84,20 @@
                 }
             }
         },
+        "vultr": {
+            "instances": {
+                "default": {
+                    "enabled": False,
+                    "ips": [],
+                    "scaling": {"min_scaling": 0, "max_scaling": 0},
+                    "plan": "",
+                    "region": "",
+                    "os_id": 1743,  # Ubuntu 22.04 LTS x64
+                    "display_name": "Vultr",
+                    "secrets": {"api_token": ""},
+                }
+            }
+        },
     },
 }
 
@@ -219,6 +233,32 @@
     "AZURE_DISPLAY_NAME", "Azure"
 )
 
+# Set Vultr config - original format for backward compatibility
+config["providers"]["vultr"]["instances"]["default"]["enabled"] = os.environ.get(
+    "VULTR_ENABLED", "False"
+) == "True"
+config["providers"]["vultr"]["instances"]["default"]["secrets"]["api_token"] = os.environ.get(
+    "VULTR_API_TOKEN"
+)
+config["providers"]["vultr"]["instances"]["default"]["scaling"]["min_scaling"] = int(
+    os.environ.get("VULTR_MIN_SCALING", 2)
+)
+config["providers"]["vultr"]["instances"]["default"]["scaling"]["max_scaling"] = int(
+    os.environ.get("VULTR_MAX_SCALING", 2)
+)
+config["providers"]["vultr"]["instances"]["default"]["plan"] = os.environ.get(
+    "VULTR_PLAN", "vc2-1c-1gb"  # 1 vCPU, 1GB RAM plan
+)
+config["providers"]["vultr"]["instances"]["default"]["region"] = os.environ.get(
+    "VULTR_REGION", "ewr"  # New Jersey region
+)
+config["providers"]["vultr"]["instances"]["default"]["os_id"] = int(
+    os.environ.get("VULTR_OS_ID", 1743)  # Ubuntu 22.04 LTS x64
+)
+config["providers"]["vultr"]["instances"]["default"]["display_name"] = os.environ.get(
+    "VULTR_DISPLAY_NAME", "Vultr"
+)
+
 # Check for additional provider instances using the new format pattern
 for provider_key in config["providers"].keys():
     provider_upper = provider_key.upper()
@@ -248,7 +288,7 @@
                 # Copy relevant fields from default instance
                 default_instance = config["providers"][provider_key]["instances"]["default"]
                 for field in ["region", "zone", "location", "ami", "spot", "datacenter", 
-                             "image_project", "image_family", "project"]:
+                             "image_project", "image_family", "project", "plan", "os_id"]:
                     if field in default_instance:
                         config["providers"][provider_key]["instances"][instance_name][field] = default_instance[field]
 
@@ -272,8 +312,10 @@
                     elif setting_name == "display_name":
                         config["providers"][provider_key]["instances"][instance_name]["display_name"] = env_value
                     elif setting_name in ["size", "region", "zone", "location", "ami", "project", 
-                                          "image_project", "image_family", "datacenter"]:
+                                          "image_project", "image_family", "datacenter", "plan"]:
                         config["providers"][provider_key]["instances"][instance_name][setting_name] = env_value
+                    elif setting_name == "os_id":
+                        config["providers"][provider_key]["instances"][instance_name]["os_id"] = int(env_value)
                     elif setting_name == "spot":
                         config["providers"][provider_key]["instances"][instance_name]["spot"] = env_value == "True"
                     elif setting_name in default_instance["secrets"]:

diff --git a/cloudproxy/providers/vultr/__init__.py b/cloudproxy/providers/vultr/__init__.py
-Original file line number
+Diff line change
@@ Expand Up / @@ -153,3 +153,4 @@ pnpm-debug.log* @@
     *.sln
     *.sw?
     .cursor-project-context
+    CLAUDE.md