### Install CloudProxy from source

Source: https://github.com/claffin/cloudproxy/blob/main/docs/python-package-usage.md

Commands to clone the repository and install in development mode or build from source.

```bash
# Clone the repository
git clone https://github.com/claffin/cloudproxy.git
cd cloudproxy

# Install in development mode
pip install -e .

# Or build and install
pip install build
python -m build
pip install dist/cloudproxy-*.whl  # Use the generated wheel file
```

--------------------------------

### Install project dependencies

Source: https://github.com/claffin/cloudproxy/blob/main/cloudproxy-ui/README.md

Run this command to install all required project dependencies.

```bash
yarn install
```

--------------------------------

### Install CloudProxy via pip

Source: https://github.com/claffin/cloudproxy/blob/main/docs/python-package-usage.md

Standard installation command for development environments.

```bash
pip install cloudproxy
```

--------------------------------

### Install CloudProxy Python Package

Source: https://github.com/claffin/cloudproxy/blob/main/README.md

Install the package from PyPI or set up a local development environment.

```bash
# Install from PyPI
pip install cloudproxy

# Or install from source for development
git clone https://github.com/claffin/cloudproxy.git
cd cloudproxy
pip install -e .
```

--------------------------------

### Get Provider Instance Details

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieve configuration for a specific provider instance in multi-account setups.

```bash
curl -X 'GET' 'http://localhost:8000/providers/digitalocean/secondary' \
  -H 'accept: application/json'
```

--------------------------------

### Python Example: Get and Use a Random Proxy

Source: https://github.com/claffin/cloudproxy/blob/main/README.md

Demonstrates how to fetch a random proxy URL using the requests library and then use it to make an HTTPS request.

```python
import requests

# Get a random proxy
response = requests.get("http://localhost:8000/random").json()
proxy_url = response["proxy"]["url"]

# Use the proxy
proxies = {"http": proxy_url, "https": proxy_url}
result = requests.get("https://api.ipify.org", proxies=proxies)
```

--------------------------------

### Default Instance Configuration Example

Source: https://github.com/claffin/cloudproxy/blob/main/docs/gcp.md

Example of environment variables for configuring the default GCP instance for CloudProxy. This includes enabling the provider, specifying credentials, project, and zone.

```text
GCP_ENABLED=True
GCP_SA_JSON=/path/to/service-account-key.json
GCP_PROJECT=your-project-id
GCP_ZONE=us-central1-a
GCP_MIN_SCALING=2
```

--------------------------------

### Start development server

Source: https://github.com/claffin/cloudproxy/blob/main/cloudproxy-ui/README.md

Compiles the project and enables hot-reloading for development.

```bash
yarn serve
```

--------------------------------

### Start CloudProxy service programmatically

Source: https://github.com/claffin/cloudproxy/blob/main/docs/python-package-usage.md

Initializes environment variables and starts the service within a Python script.

```python
import os
from cloudproxy.providers import manager
import cloudproxy.main as cloudproxy

# Set required environment variables
os.environ["PROXY_USERNAME"] = "your_username"
os.environ["PROXY_PASSWORD"] = "your_password"

# Configure provider(s)
os.environ["DIGITALOCEAN_ENABLED"] = "True"
os.environ["DIGITALOCEAN_ACCESS_TOKEN"] = "your_digitalocean_token"

# Start the CloudProxy service
cloudproxy.start()
```

--------------------------------

### Additional GCP Instance Configuration Example

Source: https://github.com/claffin/cloudproxy/blob/main/docs/gcp.md

Example of environment variables for configuring a second, named GCP instance ('EUROPE') for CloudProxy. This allows for multi-account support with distinct settings.

```text
GCP_EUROPE_ENABLED=True
GCP_EUROPE_SA_JSON=/path/to/europe-service-account-key.json
GCP_EUROPE_PROJECT=europe-project-id
GCP_EUROPE_ZONE=europe-west1-b
GCP_EUROPE_MIN_SCALING=1
GCP_EUROPE_SIZE=e2-micro
GCP_EUROPE_DISPLAY_NAME=Europe GCP Account
```

--------------------------------

### Set Up Development Environment

Source: https://github.com/claffin/cloudproxy/blob/main/README.md

Clone the repository, install dependencies, and run the application locally.

```bash
# Clone the repository
git clone https://github.com/claffin/cloudproxy.git
cd cloudproxy

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements.txt

# Run the application locally
python -m cloudproxy
```

--------------------------------

### Start CloudProxy with Docker

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Use this command to launch the CloudProxy container with necessary environment variables for authentication and provider configuration.

```bash
docker run -d --name cloudproxy \
  -e PROXY_USERNAME='user' \
  -e PROXY_PASSWORD='pass' \
  -e DIGITALOCEAN_ENABLED=True \
  -e DIGITALOCEAN_ACCESS_TOKEN='your_token' \
  -p 8000:8000 \
  laffin/cloudproxy:latest
```

--------------------------------

### Get Provider Instance Details

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieve configuration for a specific provider instance when using multi-account setups.

```APIDOC
## GET /providers/{provider_name}/{instance_name}

### Description
Retrieve configuration for a specific provider instance when using multi-account setups.

### Method
GET

### Endpoint
/providers/{provider_name}/{instance_name}

### Parameters
#### Path Parameters
- **provider_name** (string) - Required - The name of the cloud provider (e.g., 'digitalocean').
- **instance_name** (string) - Required - The name of the specific instance (e.g., 'secondary').

### Response
#### Success Response (200)
- **metadata** (object) - Metadata about the response.
- **message** (string) - Confirmation message.
- **provider** (string) - The name of the cloud provider.
- **instance** (string) - The name of the instance.
- **config** (object) - Configuration details for the instance.
  - **enabled** (boolean) - Whether the instance is enabled.
  - **ips** (array) - List of current proxy IPs for the instance.
  - **scaling** (object) - Scaling configuration for the instance.
    - **min_scaling** (integer) - Minimum number of proxies.
    - **max_scaling** (integer) - Maximum number of proxies.
  - **size** (string) - Instance size.
  - **region** (string) - Cloud region.
  - **display_name** (string) - Display name for the instance (optional).

#### Response Example
```json
{
  "metadata": {},
  "message": "Provider 'digitalocean' instance 'secondary' configuration retrieved successfully",
  "provider": "digitalocean",
  "instance": "secondary",
  "config": {
    "enabled": true,
    "ips": ["192.168.1.2"],
    "scaling": {"min_scaling": 1, "max_scaling": 3},
    "size": "s-1vcpu-1gb",
    "region": "nyc1",
    "display_name": "US Account"
  }
}
```
```

--------------------------------

### GCP Service Account Setup

Source: https://github.com/claffin/cloudproxy/blob/main/docs/security.md

Create and configure a dedicated service account with minimal IAM roles.

```bash
# Create service account with minimal permissions
gcloud iam service-accounts create cloudproxy-sa \
  --display-name="CloudProxy Service Account"

# Grant only required roles
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:cloudproxy-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/compute.instanceAdmin"
```

--------------------------------

### Install Test Dependencies

Source: https://github.com/claffin/cloudproxy/blob/main/CONTRIBUTING.md

Before running tests locally, install the necessary testing libraries, including pytest, pytest-mock, and pytest-cov, using pip.

```bash
pip install pytest pytest-mock pytest-cov
```

--------------------------------

### Development Setup for Hetzner Integration

Source: https://github.com/claffin/cloudproxy/blob/main/docs/hetzner.md

Enable Hetzner integration for development purposes by setting environment variables and running the CloudProxy module.

```bash
export HETZNER_ENABLED=True
export HETZNER_API_TOKEN="your-api-token"
python -m cloudproxy
```

--------------------------------

### Setup Selenium with Proxy

Source: https://github.com/claffin/cloudproxy/blob/main/docs/python-package-usage.md

Configures Selenium WebDriver to use a proxy server obtained from CloudProxy. This example uses Chrome options to set the proxy server address.

```python
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
import requests

def get_proxy():
    response = requests.get("http://localhost:8000/random").json()
    proxy_details = response["proxy"]
    return proxy_details["ip"], proxy_details["port"]

def setup_selenium_with_proxy():
    proxy_ip, proxy_port = get_proxy()
    
    options = Options()
    options.add_argument(f'--proxy-server={proxy_ip}:{proxy_port}')
    
    # If proxy requires authentication
    # You'll need to use a proxy authentication extension or plugin
    
    driver = webdriver.Chrome(options=options)
    return driver

# Example usage
driver = setup_selenium_with_proxy()
driver.get("https://www.whatismyip.com/")
# The page should show the IP of your proxy
```

--------------------------------

### Configure GitHub Actions for Testing

Source: https://github.com/claffin/cloudproxy/blob/main/cloudproxy-ui/tests/README.md

Example configuration for running unit and E2E tests within a CI pipeline.

```yaml
# GitHub Actions example
- name: Run Unit Tests
  run: npm run test:run

- name: Run E2E Tests
  run: |
    npm run serve &
    npx wait-on http://localhost:8080
    npm run test:e2e
```

--------------------------------

### Get Provider Details

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieve detailed configuration and status for a specific provider.

```bash
curl -X 'GET' 'http://localhost:8000/providers/digitalocean' \
  -H 'accept: application/json'
```

--------------------------------

### Configure Additional Hetzner Instance

Source: https://github.com/claffin/cloudproxy/blob/main/docs/hetzner.md

Use the `INSTANCENAME_` prefix to configure additional, independent Hetzner Cloud accounts. This example shows setting up a second account in Finland.

```bash
HETZNER_FINLAND_ENABLED=True
HETZNER_FINLAND_API_TOKEN=your_second_token
HETZNER_FINLAND_LOCATION=hel1
HETZNER_FINLAND_MIN_SCALING=3
HETZNER_FINLAND_SIZE=cx11
HETZNER_FINLAND_DISPLAY_NAME=Finland Hetzner Account
```

--------------------------------

### GET /

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

List available proxy servers with optional pagination.

```APIDOC
## GET /

### Description
List available proxy servers.

### Method
GET

### Endpoint
/

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - The number of items to skip.
- **limit** (integer) - Optional - The maximum number of items to return.

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata including ID and timestamp.
- **total** (integer) - Total number of proxies.
- **proxies** (array) - List of proxy objects.
```

--------------------------------

### GET /providers

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Lists all configured proxy providers and their instances.

```APIDOC
## GET /providers

### Description
Returns configuration and status for all providers, including all instances.

### Method
GET

### Endpoint
/providers

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata
- **providers** (object) - Map of provider configurations

#### Response Example
{
  "metadata": {},
  "providers": {
    "digitalocean": {
      "enabled": true,
      "ips": ["192.168.1.1"],
      "scaling": {
        "min_scaling": 2,
        "max_scaling": 5
      },
      "size": "s-1vcpu-1gb",
      "region": "lon1",
      "instances": {}
    }
  }
}
```

--------------------------------

### Docker Deployment with DigitalOcean

Source: https://github.com/claffin/cloudproxy/blob/main/README.md

Quick start deployment of CloudProxy using Docker with DigitalOcean as the provider. Requires setting environment variables for proxy credentials and DigitalOcean access.

```bash
docker run -d \
  -e PROXY_USERNAME='your_username' \
  -e PROXY_PASSWORD='your_password' \
  -e DIGITALOCEAN_ENABLED=True \
  -e DIGITALOCEAN_ACCESS_TOKEN='your_token' \
  -p 8000:8000 \
  laffin/cloudproxy:latest
```

--------------------------------

### Initialize CloudProxy with custom rotation

Source: https://github.com/claffin/cloudproxy/blob/main/docs/python-package-usage.md

Sets the proxy age limit via environment variables before initializing the manager and starting the service.

```python
# Set proxies to be replaced after 3600 seconds (1 hour)
os.environ["AGE_LIMIT"] = "3600"

# Then start CloudProxy as usual
from cloudproxy.providers import manager
import cloudproxy.main as cloudproxy

manager.init_schedule()
cloudproxy.start()
```

--------------------------------

### Quick Docker Deployment with DigitalOcean

Source: https://context7.com/claffin/cloudproxy/llms.txt

Quickly deploy CloudProxy using Docker with DigitalOcean as the cloud provider. Ensure you have Docker installed and a DigitalOcean access token.

```bash
# Quick start with DigitalOcean
docker run -d \
  -e PROXY_USERNAME='your_username' \
  -e PROXY_PASSWORD='your_password' \
  -e DIGITALOCEAN_ENABLED=True \
  -e DIGITALOCEAN_ACCESS_TOKEN='your_token' \
  -e DIGITALOCEAN_REGION='lon1' \
  -e DIGITALOCEAN_MIN_SCALING=2 \
  -p 8000:8000 \
  laffin/cloudproxy:latest
```

--------------------------------

### Development Setup for DigitalOcean

Source: https://github.com/claffin/cloudproxy/blob/main/docs/digitalocean.md

For development purposes, you can enable DigitalOcean integration and run CloudProxy using Python. Set the necessary environment variables before executing the Python module.

```bash
export DIGITALOCEAN_ENABLED=True
export DIGITALOCEAN_ACCESS_TOKEN="your-token-here"
python -m cloudproxy
```

--------------------------------

### GET /providers/{provider}/{instance}

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

Retrieves the configuration details for a specific provider instance.

```APIDOC
## GET /providers/{provider}/{instance}

### Description
Retrieves the configuration details for a specific provider instance.

### Method
GET

### Endpoint
/providers/{provider}/{instance}

### Parameters
#### Path Parameters
- **provider** (string) - Required - The name of the provider (e.g., digitalocean)
- **instance** (string) - Required - The name of the instance (e.g., secondary)

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata including ID and timestamp
- **message** (string) - Success message
- **provider** (string) - Provider name
- **instance** (string) - Instance name
- **config** (object) - Configuration details including enabled status, IPs, scaling, size, region, and display name

#### Response Example
{
  "metadata": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2024-02-24T08:00:00Z"
  },
  "message": "Provider 'digitalocean' instance 'secondary' configuration retrieved successfully",
  "provider": "digitalocean",
  "instance": "secondary",
  "config": {
    "enabled": true,
    "ips": ["192.168.1.2"],
    "scaling": {
      "min_scaling": 1,
      "max_scaling": 3
    },
    "size": "s-1vcpu-1gb",
    "region": "nyc1",
    "display_name": "US Account"
  }
}
```

--------------------------------

### Start CloudProxy with Docker

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

Run CloudProxy as a Docker container, configuring essential environment variables for authentication and cloud provider integration. Ensure CloudProxy is ready by checking its health endpoint.

```bash
# Start CloudProxy with Docker
docker run -d --name cloudproxy \
  -e PROXY_USERNAME='myuser' \
  -e PROXY_PASSWORD='mypass' \
  -e DIGITALOCEAN_ENABLED=True \
  -e DIGITALOCEAN_ACCESS_TOKEN='your_token' \
  -p 8000:8000 \
  laffin/cloudproxy:latest

# Wait for CloudProxy to be ready
until curl -s http://localhost:8000/health > /dev/null; do
  echo "Waiting for CloudProxy to start..."
  sleep 2
done
```

--------------------------------

### List Available Proxies Response

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Example response for the list proxies endpoint.

```json
{
  "metadata": { ... },
  "total": 5,
  "proxies": [
    {
      "ip": "192.168.1.1",
      "port": 8899,
      "auth_enabled": true,
      "url": "http://username:password@192.168.1.1:8899",
      "provider": "digitalocean",
      "instance": "default",
      "display_name": "My DigitalOcean Instance"
    }
  ]
}
```

--------------------------------

### Development Setup for Vultr Integration

Source: https://github.com/claffin/cloudproxy/blob/main/docs/vultr.md

This command is for development purposes, enabling Vultr integration and running CloudProxy directly using Python. Ensure Vultr is enabled and your API token is set as an environment variable.

```bash
export VULTR_ENABLED=True
export VULTR_API_TOKEN="your-token-here"
python -m cloudproxy
```

--------------------------------

### Development Setup for CloudProxy with GCP

Source: https://github.com/claffin/cloudproxy/blob/main/docs/gcp.md

Configure CloudProxy for development using Python. Set the necessary environment variables for GCP integration before running the CloudProxy module.

```bash
export GCP_ENABLED=True
export GCP_SA_JSON="/path/to/service-account-key.json"
export GCP_PROJECT="your-project-id"
python -m cloudproxy
```

--------------------------------

### Development Setup for AWS with CloudProxy

Source: https://github.com/claffin/cloudproxy/blob/main/docs/aws.md

For development purposes, you can enable AWS and run CloudProxy directly using Python. Ensure your AWS environment variables are exported.

```bash
export AWS_ENABLED=True
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
python -m cloudproxy
```

--------------------------------

### Configure Docker Network for CloudProxy

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Setup a dedicated network to allow other containers to communicate with the CloudProxy service.

```bash
# Create a network for your services
docker network create proxy-network

# Run CloudProxy on the network
docker run -d --name cloudproxy \
  --network proxy-network \
  -p 8000:8000 \
  --env-file .env \
  laffin/cloudproxy:latest

# Other containers can access it at http://cloudproxy:8000
docker run --network proxy-network alpine \
  wget -qO- http://cloudproxy:8000/random
```

--------------------------------

### Write Unit Test with Vitest

Source: https://github.com/claffin/cloudproxy/blob/main/cloudproxy-ui/tests/README.md

Example of a basic component test using Vue Test Utils and Vitest.

```javascript
import { mount } from '@vue/test-utils';
import { describe, it, expect } from 'vitest';
import MyComponent from '@/components/MyComponent.vue';

describe('MyComponent', () => {
  it('renders correctly', () => {
    const wrapper = mount(MyComponent);
    expect(wrapper.find('.my-class').exists()).toBe(true);
  });
});
```

--------------------------------

### Write E2E Test with Cypress

Source: https://github.com/claffin/cloudproxy/blob/main/cloudproxy-ui/tests/README.md

Example of a basic user interaction test using the Cypress API.

```javascript
describe('My Feature', () => {
  it('performs user action', () => {
    cy.visit('/');
    cy.get('#my-button').click();
    cy.get('.result').should('contain', 'Success');
  });
});
```

--------------------------------

### Rolling Deployment Status Response Example

Source: https://github.com/claffin/cloudproxy/blob/main/docs/rolling-deployments.md

This JSON response details the current rolling deployment configuration and the status of proxies for a given provider. It includes counts of healthy, pending, and recycling proxies, along with their IP addresses.

```json
{
  "metadata": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "message": "Rolling deployment status retrieved successfully",
  "config": {
    "enabled": true,
    "min_available": 3,
    "batch_size": 2
  },
  "status": {
    "digitalocean/default": {
      "healthy": 3,
      "pending": 0,
      "pending_recycle": 1,
      "recycling": 1,
      "last_update": "2024-01-01T00:00:00Z",
      "healthy_ips": ["192.168.1.1", "192.168.1.2", "192.168.1.3"],
      "pending_recycle_ips": ["192.168.1.4"],
      "recycling_ips": ["192.168.1.5"]
    }
  }
}
```

--------------------------------

### Get Provider Instance Configuration

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

Retrieves the configuration for a specific provider instance. Use this to check current settings like scaling, region, and enabled status.

```bash
curl -X 'GET' 'http://localhost:8000/providers/digitalocean/secondary' -H 'accept: application/json'
```

--------------------------------

### List All Providers

Source: https://context7.com/claffin/cloudproxy/llms.txt

Get configuration and status for all configured cloud providers, including all instances and their current proxy IPs.

```APIDOC
## GET /providers

### Description
Get configuration and status for all configured cloud providers, including all instances and their current proxy IPs.

### Method
GET

### Endpoint
/providers

### Response
#### Success Response (200)
- **metadata** (object) - Metadata about the response.
- **providers** (object) - An object containing configurations for each cloud provider.
  - **provider_name** (object) - Configuration for a specific provider (e.g., digitalocean, aws).
    - **enabled** (boolean) - Whether the provider is enabled.
    - **ips** (array) - List of current proxy IPs for the provider.
    - **scaling** (object) - Scaling configuration.
      - **min_scaling** (integer) - Minimum number of proxies.
      - **max_scaling** (integer) - Maximum number of proxies.
    - **size** (string) - Instance size.
    - **region** (string) - Cloud region.
    - **instances** (object) - Configuration for specific instances within the provider.
      - **instance_name** (object) - Configuration for a named instance (e.g., default, secondary).
        - **enabled** (boolean) - Whether the instance is enabled.
        - **ips** (array) - List of current proxy IPs for the instance.
        - **scaling** (object) - Scaling configuration for the instance.
        - **size** (string) - Instance size.
        - **region** (string) - Cloud region.

#### Response Example
```json
{
  "metadata": {},
  "providers": {
    "digitalocean": {
      "enabled": true,
      "ips": ["192.168.1.1", "192.168.1.2"],
      "scaling": {"min_scaling": 2, "max_scaling": 2},
      "size": "s-1vcpu-1gb",
      "region": "lon1",
      "instances": {
        "default": {
          "enabled": true,
          "ips": ["192.168.1.1"],
          "scaling": {"min_scaling": 2, "max_scaling": 2},
          "size": "s-1vcpu-1gb",
          "region": "lon1"
        },
        "secondary": {
          "enabled": true,
          "ips": ["192.168.1.2"],
          "scaling": {"min_scaling": 1, "max_scaling": 3},
          "size": "s-1vcpu-1gb",
          "region": "nyc1"
        }
      }
    },
    "aws": {"enabled": false, ...}
  }
}
```
```

--------------------------------

### Get Random Proxy Response

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Example response for the random proxy endpoint.

```json
{
  "metadata": { ... },
  "message": "Random proxy retrieved successfully",
  "proxy": {
    "ip": "192.168.1.1",
    "port": 8899,
    "auth_enabled": true,
    "url": "http://username:password@192.168.1.1:8899",
    "provider": "digitalocean",
    "instance": "default",
    "display_name": "My DigitalOcean Instance"
  }
}
```

--------------------------------

### Get Specific CloudProxy Provider Details

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Retrieves detailed configuration and instance information for a single specified provider. Use this to inspect a particular cloud provider's setup.

```json
{
  "metadata": { ... },
  "message": "Provider 'digitalocean' configuration retrieved successfully",
  "provider": {
    "enabled": true,
    "ips": ["192.168.1.1"],
    "scaling": {
      "min_scaling": 2,
      "max_scaling": 5
    },
    "size": "s-1vcpu-1gb",
    "region": "lon1"
  },
  "instances": {
    "default": {
      "enabled": true,
      "ips": ["192.168.1.1", "192.168.1.2"],
      "scaling": {
        "min_scaling": 2,
        "max_scaling": 5
      },
      "size": "s-1vcpu-1gb",
      "region": "lon1"
    },
    "second-account": {
      "enabled": true,
      "ips": ["192.168.1.3", "192.168.1.4"],
      "scaling": {
        "min_scaling": 1,
        "max_scaling": 3
      },
      "size": "s-1vcpu-1gb",
      "region": "nyc1"
    }
  }
}
```

--------------------------------

### GET /providers

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

Get information about configured proxy providers.

```APIDOC
## GET /providers

### Description
Get information about configured proxy providers.

### Method
GET

### Endpoint
/providers

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata.
- **providers** (object) - Map of provider configurations.
```

--------------------------------

### Configure Multiple Cloud Providers

Source: https://context7.com/claffin/cloudproxy/llms.txt

Set up various cloud providers like DigitalOcean, AWS, Hetzner, and GCP using environment variables. Configure regions, scaling, and specific account details for each provider.

```bash
# DigitalOcean - Primary account (London)
DIGITALOCEAN_ENABLED=True
DIGITALOCEAN_ACCESS_TOKEN=your_do_token
DIGITALOCEAN_REGION=lon1
DIGITALOCEAN_MIN_SCALING=2

# DigitalOcean - Secondary account (New York)
DIGITALOCEAN_USEAST_ENABLED=True
DIGITALOCEAN_USEAST_ACCESS_TOKEN=your_second_do_token
DIGITALOCEAN_USEAST_REGION=nyc1
DIGITALOCEAN_USEAST_MIN_SCALING=3
DIGITALOCEAN_USEAST_DISPLAY_NAME=US East Account

# AWS - Default account
AWS_ENABLED=True
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
AWS_MIN_SCALING=2
AWS_SIZE=t2.micro
AWS_SPOT=True

# AWS - EU account with spot instances
AWS_EU_ENABLED=True
AWS_EU_ACCESS_KEY_ID=your_eu_access_key
AWS_EU_SECRET_ACCESS_KEY=your_eu_secret_key
AWS_EU_REGION=eu-west-1
AWS_EU_MIN_SCALING=1
AWS_EU_SPOT=True
AWS_EU_DISPLAY_NAME=EU Account

# Hetzner
HETZNER_ENABLED=True
HETZNER_API_TOKEN=your_hetzner_token
HETZNER_LOCATION=nbg1
HETZNER_MIN_SCALING=2

# GCP
GCP_ENABLED=True
GCP_PROJECT=your_project_id
GCP_SA_JSON=/path/to/service-account.json
GCP_ZONE=us-central1-a
GCP_MIN_SCALING=2
```

--------------------------------

### List Available Proxy Servers

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

Retrieve a list of available proxy servers using the GET / endpoint with optional offset and limit parameters for pagination. The response includes metadata and a list of proxy server details.

```bash
curl -X 'GET' 'http://localhost:8000/?offset=0&limit=10' -H 'accept: application/json'
```

--------------------------------

### Initialize and Use CloudProxy

Source: https://context7.com/claffin/cloudproxy/llms.txt

Configure environment variables for proxy authentication and cloud provider settings, then initialize CloudProxy, wait for proxies, and retrieve their IPs for use in requests.

```python
os.environ["PROXY_USERNAME"] = "your_username"
os.environ["PROXY_PASSWORD"] = "your_password"
os.environ["DIGITALOCEAN_ENABLED"] = "True"
os.environ["DIGITALOCEAN_ACCESS_TOKEN"] = "your_digitalocean_token"
os.environ["DIGITALOCEAN_MIN_SCALING"] = "3"

# Initialize CloudProxy infrastructure
manager.init_schedule()

# Wait for proxies to be provisioned
print("Waiting for proxies...")
for _ in range(30):
    proxies = manager.get_all_ips()
    if proxies:
        break
    time.sleep(10)

# Get all available proxy IPs
all_ips = manager.get_all_ips()
print(f"Available proxies: {all_ips}")

# Get provider-specific IPs
do_ips = manager.get_provider_ips("digitalocean")

# Get instance-specific IPs
do_default_ips = manager.get_provider_instance_ips("digitalocean", "default")

# Format proxy URL for requests
if all_ips:
    random_ip = random.choice(all_ips)
    proxy_url = f"http://{os.environ['PROXY_USERNAME']}:{os.environ['PROXY_PASSWORD']}@{random_ip}:8899"

    import requests
    response = requests.get(
        "https://api.ipify.org?format=json",
        proxies={"http": proxy_url, "https": proxy_url}
    )
    print(f"Your IP: {response.json()['ip']}")
```

--------------------------------

### List All Providers

Source: https://context7.com/claffin/cloudproxy/llms.txt

Fetch configuration and status for all configured cloud providers and their instances.

```bash
curl -X 'GET' 'http://localhost:8000/providers' \
  -H 'accept: application/json'
```

--------------------------------

### Get Random Proxy Server

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

Fetch a random proxy server from the available pool using the GET /random endpoint. The response contains metadata and details of the selected proxy server.

```bash
curl -X 'GET' 'http://localhost:8000/random' -H 'accept: application/json'
```

--------------------------------

### Manage Multiple Provider Instances

Source: https://github.com/claffin/cloudproxy/blob/main/docs/python-package-usage.md

Demonstrates how to configure and manage multiple instances of the same proxy provider (e.g., DigitalOcean) with different API keys and settings. This allows for more flexible proxy management.

```python
import os
from cloudproxy.providers import manager

# Setup the first DigitalOcean instance (default)
os.environ["DIGITALOCEAN_ENABLED"] = "True"
os.environ["DIGITALOCEAN_ACCESS_TOKEN"] = "first_token"
os.environ["DIGITALOCEAN_REGION"] = "lon1"
os.environ["DIGITALOCEAN_MIN_SCALING"] = "2"

# Setup a second DigitalOcean instance
os.environ["DIGITALOCEAN_SECONDARY_ENABLED"] = "True"
os.environ["DIGITALOCEAN_SECONDARY_ACCESS_TOKEN"] = "second_token"
os.environ["DIGITALOCEAN_SECONDARY_REGION"] = "nyc1"
os.environ["DIGITALOCEAN_SECONDARY_MIN_SCALING"] = "3"

# Initialize the manager
manager.init_schedule()

# Get all proxies from the first instance
do_proxies = manager.get_provider_instance_ips("digitalocean", "default")

# Get all proxies from the second instance
do_secondary_proxies = manager.get_provider_instance_ips("digitalocean", "secondary")
```

--------------------------------

### Get Cloud Providers

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

Retrieve information about configured cloud providers and their proxy server instances using the GET /providers endpoint. This includes details on enabled status, IP addresses, scaling configurations, and instance sizes.

```bash
curl -X 'GET' 'http://localhost:8000/providers' -H 'accept: application/json'
```

--------------------------------

### GET /random

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api-examples.md

Retrieve a random proxy server.

```APIDOC
## GET /random

### Description
Retrieve a random proxy server.

### Method
GET

### Endpoint
/random

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata.
- **message** (string) - Success message.
- **proxy** (object) - The random proxy details.
```

--------------------------------

### GET /auth

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieves the current proxy authentication configuration.

```APIDOC
## GET /auth

### Description
Get the current proxy authentication configuration.

### Method
GET

### Endpoint
`/auth`

### Response
#### Success Response (200)
- **username** (string) - The username for authentication.
- **password** (string) - The password for authentication.
- **auth_enabled** (boolean) - Indicates if authentication is enabled.

#### Response Example
```json
{
  "username": "your_username",
  "password": "your_password",
  "auth_enabled": true
}
```
```

--------------------------------

### GET /auth

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Returns the current authentication configuration for the service.

```APIDOC
## GET /auth

### Description
Returns the current authentication configuration.

### Method
GET

### Endpoint
/auth

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata
- **auth** (object) - Authentication settings including username/password status and IP restrictions

#### Response Example
{
  "metadata": {},
  "auth": {
    "username_configured": true,
    "password_configured": true,
    "only_host_ip": false,
    "host_ip": "192.168.1.100"
  }
}
```

--------------------------------

### GET /health

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Returns the health status of the CloudProxy service.

```APIDOC
## GET /health

### Description
Returns the health status of the CloudProxy service.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Service status
- **timestamp** (string) - ISO 8601 timestamp

#### Response Example
{
  "status": "healthy",
  "timestamp": "2024-02-24T08:00:00Z"
}
```

--------------------------------

### Validate Service Account and List Instances

Source: https://github.com/claffin/cloudproxy/blob/main/docs/gcp.md

Use these commands to activate your service account with a key file and list compute engine instances. Ensure your service account has the necessary Compute Admin and Service Account User roles.

```bash
gcloud auth activate-service-account --key-file=key.json
```

```bash
gcloud compute instances list
```

--------------------------------

### GET /rolling/digitalocean/default

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieves the status for a specific instance within a provider.

```APIDOC
## GET /rolling/digitalocean/default

### Description
Retrieves the status for a specific instance within a provider.

### Method
GET

### Endpoint
`/rolling/digitalocean/default`

### Request Example
```bash
curl -X 'GET' 'http://localhost:8000/rolling/digitalocean/default' -H 'accept: application/json'
```

### Response
#### Success Response (200)
- **status** (object) - Details about the rolling deployment status for the specific instance.

#### Response Example
```json
{
  "status": {
    "provider": "digitalocean",
    "instance_id": "default",
    "status": "active"
  }
}
```
```

--------------------------------

### GET /rolling/digitalocean

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieves the status for a specific provider, in this case, DigitalOcean.

```APIDOC
## GET /rolling/digitalocean

### Description
Retrieves the status for a specific provider.

### Method
GET

### Endpoint
`/rolling/digitalocean`

### Request Example
```bash
curl -X 'GET' 'http://localhost:8000/rolling/digitalocean' -H 'accept: application/json'
```

### Response
#### Success Response (200)
- **status** (object) - Details about the rolling deployment status for the provider.

#### Response Example
```json
{
  "status": {
    "provider": "digitalocean",
    "instances": [
      {
        "id": "instance-1",
        "status": "active"
      }
    ]
  }
}
```
```

--------------------------------

### Build for production

Source: https://github.com/claffin/cloudproxy/blob/main/cloudproxy-ui/README.md

Compiles and minifies the project assets for production deployment.

```bash
yarn build
```

--------------------------------

### GET /providers/{provider}

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Retrieves detailed information for a specific provider.

```APIDOC
## GET /providers/{provider}

### Description
Returns detailed information for a specific provider, including all instances.

### Method
GET

### Endpoint
/providers/{provider}

### Parameters
#### Path Parameters
- **provider** (string) - Required - The name of the provider

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata
- **message** (string) - Success message
- **provider** (object) - Provider configuration
- **instances** (object) - Map of instances for the provider

#### Response Example
{
  "metadata": {},
  "message": "Provider 'digitalocean' configuration retrieved successfully",
  "provider": {},
  "instances": {}
}
```

--------------------------------

### Remove Proxy Response

Source: https://github.com/claffin/cloudproxy/blob/main/docs/api.md

Example response for the remove proxy endpoint.

```json
{
  "metadata": { ... },
  "message": "Proxy scheduled for deletion",
  "proxy": {
    "ip": "192.168.1.1",
    "port": 8899,
    "auth_enabled": true,
    "url": "http://username:password@192.168.1.1:8899"
  }
}
```

--------------------------------

### Configure Rolling Deployments

Source: https://github.com/claffin/cloudproxy/blob/main/README.md

Set environment variables to enable zero-downtime proxy recycling.

```bash
# Enable rolling deployments
ROLLING_DEPLOYMENT=True

# Minimum proxies to keep available during recycling
ROLLING_MIN_AVAILABLE=3
```

--------------------------------

### Deploy CloudProxy with Docker

Source: https://github.com/claffin/cloudproxy/blob/main/README.md

Run the CloudProxy container using an environment file for configuration.

```bash
docker run -d \
  --env-file .env \
  -p 8000:8000 \
  laffin/cloudproxy:0.6.0-beta  # Use specific version tag
```

--------------------------------

### Get Scheduled Proxies

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieve a list of proxies currently scheduled for restart.

```bash
curl -X 'GET' 'http://localhost:8000/restart' -H 'accept: application/json'
```

--------------------------------

### UI Build Command

Source: https://github.com/claffin/cloudproxy/blob/main/README.md

Command to build the frontend static files for the CloudProxy UI.

```bash
npm run build
```

--------------------------------

### Develop CloudProxy UI

Source: https://github.com/claffin/cloudproxy/blob/main/README.md

Manage dependencies and build the frontend interface.

```bash
# Navigate to UI directory
cd cloudproxy-ui

# Install dependencies
npm install

# Run development server (hot reload enabled)
npm run serve

# Build for production
npm run build
```

--------------------------------

### Get Instance Status

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieve the status of a specific proxy instance within a provider.

```bash
curl -X 'GET' 'http://localhost:8000/rolling/digitalocean/default' -H 'accept: application/json'
```

--------------------------------

### Get Provider Status

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieve the status of proxies for a specific provider like DigitalOcean.

```bash
curl -X 'GET' 'http://localhost:8000/rolling/digitalocean' -H 'accept: application/json'
```

--------------------------------

### Run CloudProxy with Hetzner using Docker

Source: https://github.com/claffin/cloudproxy/blob/main/docs/hetzner.md

Deploy CloudProxy with Hetzner integration using Docker. Ensure to set required environment variables for authentication and location.

```bash
# Run with Docker (recommended)
docker run -d \
  -e PROXY_USERNAME='your_username' \
  -e PROXY_PASSWORD='your_password' \
  -e HETZNER_ENABLED=True \
  -e HETZNER_API_TOKEN="your-api-token" \
  -e HETZNER_LOCATION="nbg1" \
  -p 8000:8000 \
  laffin/cloudproxy:latest
```

```bash
# Or using an environment file
cat > .env << EOF
PROXY_USERNAME=your_username
PROXY_PASSWORD=your_password
HETZNER_ENABLED=True
HETZNER_API_TOKEN=your-api-token
HETZNER_LOCATION=nbg1
EOF

docker run -d --env-file .env -p 8000:8000 laffin/cloudproxy:latest
```

--------------------------------

### Get List of Proxies Scheduled for Restart

Source: https://context7.com/claffin/cloudproxy/llms.txt

Retrieves a list of proxies that are scheduled for a restart.

```APIDOC
## GET /restart

### Description
Get list of proxies scheduled for restart.

### Method
GET

### Endpoint
/restart

### Response
#### Success Response (200)
- **proxies** (array) - List of proxy identifiers scheduled for restart.

#### Response Example
```json
{
  "metadata": {},
  "proxies": [
    "http://username:password@192.168.1.1:8899"
  ]
}
```
```

--------------------------------

### Get Rolling Deployment Status

Source: https://github.com/claffin/cloudproxy/blob/main/docs/rolling-deployments.md

Retrieve the current status of rolling deployments for CloudProxy.

```APIDOC
## GET /rolling

### Description
Retrieves the overall rolling deployment status.

### Method
GET

### Endpoint
/rolling

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **metadata** (object) - Request metadata including request_id and timestamp.
- **message** (string) - Confirmation message.
- **config** (object) - Current rolling deployment configuration.
  - **enabled** (boolean) - Whether rolling deployments are enabled.
  - **min_available** (integer) - Minimum number of proxies to keep available.
  - **batch_size** (integer) - Maximum number of proxies to recycle simultaneously.
- **status** (object) - Detailed status of rolling deployments per provider instance.
  - **[provider_instance_id]** (object) - Status for a specific provider instance (e.g., "digitalocean/default").
    - **healthy** (integer) - Number of healthy proxies.
    - **pending** (integer) - Number of newly created proxies not yet healthy.
    - **pending_recycle** (integer) - Number of proxies marked for recycling but not yet started.
    - **recycling** (integer) - Number of proxies currently being deleted.
    - **last_update** (string) - Timestamp of the last status update.
    - **healthy_ips** (array of strings) - List of IPs for healthy proxies.
    - **pending_recycle_ips** (array of strings) - List of IPs waiting to be recycled.
    - **recycling_ips** (array of strings) - List of IPs currently being recycled.

#### Response Example
```json
{
  "metadata": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "message": "Rolling deployment status retrieved successfully",
  "config": {
    "enabled": true,
    "min_available": 3,
    "batch_size": 2
  },
  "status": {
    "digitalocean/default": {
      "healthy": 3,
      "pending": 0,
      "pending_recycle": 1,
      "recycling": 1,
      "last_update": "2024-01-01T00:00:00Z",
      "healthy_ips": ["192.168.1.1", "192.168.1.2", "192.168.1.3"],
      "pending_recycle_ips": ["192.168.1.4"],
      "recycling_ips": ["192.168.1.5"]
    }
  }
}
```
```

```APIDOC
## GET /rolling/{provider}

### Description
Retrieves the rolling deployment status for a specific provider.

### Method
GET

### Endpoint
/rolling/{provider}

### Parameters
#### Path Parameters
- **provider** (string) - Required - The name of the provider (e.g., "digitalocean").

### Request Example
```bash
curl http://localhost:8000/rolling/digitalocean
```

### Response
#### Success Response (200)
(Same structure as GET /rolling, but filtered by provider)

#### Response Example
```json
{
  "metadata": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "message": "Rolling deployment status retrieved successfully for digitalocean",
  "config": {
    "enabled": true,
    "min_available": 3,
    "batch_size": 2
  },
  "status": {
    "digitalocean/default": {
      "healthy": 3,
      "pending": 0,
      "pending_recycle": 1,
      "recycling": 1,
      "last_update": "2024-01-01T00:00:00Z",
      "healthy_ips": ["192.168.1.1", "192.168.1.2", "192.168.1.3"],
      "pending_recycle_ips": ["192.168.1.4"],
      "recycling_ips": ["192.168.1.5"]
    }
  }
}
```
```

```APIDOC
## GET /rolling/{provider}/{instance}

### Description
Retrieves the rolling deployment status for a specific provider instance.

### Method
GET

### Endpoint
/rolling/{provider}/{instance}

### Parameters
#### Path Parameters
- **provider** (string) - Required - The name of the provider (e.g., "digitalocean").
- **instance** (string) - Required - The name of the provider instance (e.g., "default").

### Request Example
```bash
curl http://localhost:8000/rolling/digitalocean/default
```

### Response
#### Success Response (200)
(Same structure as GET /rolling, but filtered by provider and instance)

#### Response Example
```json
{
  "metadata": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "message": "Rolling deployment status retrieved successfully for digitalocean/default",
  "config": {
    "enabled": true,
    "min_available": 3,
    "batch_size": 2
  },
  "status": {
    "digitalocean/default": {
      "healthy": 3,
      "pending": 0,
      "pending_recycle": 1,
      "recycling": 1,
      "last_update": "2024-01-01T00:00:00Z",
      "healthy_ips": ["192.168.1.1", "192.168.1.2", "192.168.1.3"],
      "pending_recycle_ips": ["192.168.1.4"],
      "recycling_ips": ["192.168.1.5"]
    }
  }
}
```
```

--------------------------------

### Configure Rolling Deployments

Source: https://context7.com/claffin/cloudproxy/llms.txt

Enable and configure rolling deployments by setting environment variables for age limit, minimum available proxies, and batch size to ensure zero-downtime proxy recycling.

```bash
# Environment variables for rolling deployment
AGE_LIMIT=3600                  # Proxy age limit in seconds (1 hour)
ROLLING_DEPLOYMENT=True         # Enable rolling deployments
ROLLING_MIN_AVAILABLE=3         # Minimum healthy proxies during recycling
ROLLING_BATCH_SIZE=2            # Max proxies to recycle simultaneously

# Example scenario with 5 proxies:
# 1. All 5 reach age limit simultaneously
# 2. First 2 are recycled (batch_size=2)
# 3. 3 remain healthy (min_available=3)
# 4. When replacements are ready, next batch is recycled
# 5. Process continues until all are replaced
```