Skip to content

Cloud Providers

Jump to bottom
Eric Kochen edited this page Apr 18, 2026 · 11 revisions

purple syncs servers from sixteen cloud providers into your SSH config. Each provider is configured with an API token (or credentials file). Synced hosts get an alias prefix (a short provider identifier followed by the server name, e.g. do-web-1 for a DigitalOcean droplet named "web-1") and are tracked via comments in your config. Provider configs with multi-alias Host lines are fully supported: deleting one alias from the TUI keeps the surviving aliases and their shared directives in place.

Supported providers

Provider Auth CLI setup
AWS EC2 ~/.aws/credentials profile or access key pair purple provider add aws --profile default --regions us-east-1,eu-west-1
Azure Service principal JSON or Bearer token purple provider add azure --token /path/to/sp.json --regions SUBSCRIPTION_ID
DigitalOcean Personal access token purple provider add digitalocean --token YOUR_TOKEN
GCP Service account JSON or access token purple provider add gcp --token /path/to/sa-key.json --project my-project
Hetzner API token purple provider add hetzner --token YOUR_TOKEN
i3D.net API key purple provider add i3d --token YOUR_API_KEY
Leaseweb API key purple provider add leaseweb --token YOUR_API_KEY
Linode (Akamai) API token purple provider add linode --token YOUR_TOKEN
Oracle Cloud (OCI) ~/.oci/config file purple provider add oracle --token ~/.oci/config --compartment OCID
OVHcloud App key + app secret + consumer key purple provider add ovh --token APP_KEY:APP_SECRET:CONSUMER_KEY --project PROJECT_ID
Proxmox VE API token + cluster URL purple provider add proxmox --url https://pve:8006 --token TOKEN
Scaleway Secret key purple provider add scaleway --token YOUR_TOKEN --regions fr-par-1
Tailscale Local CLI (no token) or API key purple provider add tailscale
TransIP RSA private key or Bearer token purple provider add transip --token LOGIN:~/.transip/key.pem
UpCloud API token purple provider add upcloud --token YOUR_TOKEN
Vultr API token purple provider add vultr --token YOUR_TOKEN

Setting up a provider

Press S in the TUI to open the provider list. Navigate to a provider and press Enter to open the configuration form. The form starts with required fields only (e.g. just Token for DigitalOcean, or Token + Profile + Regions for AWS). Press Tab or Down from the last required field to expand and see optional fields like alias prefix, default user and SSH key. Fill in your credentials and confirm to start syncing. The provider list shows sync status, last sync time and stale host counts.

Provider list keybindings:

Key Action
j / k Navigate
Enter Configure provider
s Sync selected provider
d Remove provider
X Purge stale hosts for selected provider
PgDn / PgUp Page down / up
q / Esc Back (cancels running syncs)

How sync works

When you sync a provider, purple calls the provider's API to get a list of servers, then diffs them against what is already in your SSH config:

  1. Existing hosts are identified by their # purple:provider name:server_id comment (a tracking marker purple adds to each synced host block). This is how purple tracks which config entries belong to which provider
  2. New servers get an alias built from the provider prefix and a sanitized server name (e.g. do-web-1 for a DigitalOcean droplet called "web-1"). Non-alphanumeric characters become hyphens. If the alias collides with an existing host, a numeric suffix is appended
  3. Changed servers (IP, user or metadata) are updated in place. Only the changed directives are rewritten. Unchanged directives preserve their original formatting
  4. Status changes (running/stopped) are treated as volatile. A status change alone does not trigger a config rewrite. The value is stored and displayed when the host is updated for other reasons
  5. Disappeared servers are marked stale (see below) rather than removed, unless --remove is passed

Provider tags from the API response are stored in # purple:provider_tags and always exactly mirror the remote. User tags in # purple:tags are never modified by sync.

Provider credentials are stored in ~/.purple/providers (INI format, same atomic write pattern as the SSH config).

Vault SSH certificate signing per provider

Every provider config accepts two optional fields for the HashiCorp Vault SSH secrets engine: vault_role (e.g. ssh-client-signer/sign/engineer) and vault_addr (e.g. https://vault.example.com:8200). When set, all hosts synced from that provider inherit both values and purple will sign short-lived SSH certificates on connect. Individual hosts can override the inherited role via # purple:vault-ssh and the inherited address via # purple:vault-addr independently, so a host can keep the provider's role while pointing at a different Vault server or vice versa. With vault_addr configured you no longer need to export VAULT_ADDR in your shell. See Vault SSH Certificates for setup, prerequisites, the V bulk-sign key and troubleshooting.

Syncing

In the TUI, press s on a provider in the provider list to sync it. Syncs run in background threads with cancel support (press q/Esc to cancel running syncs). Auto-sync runs on startup for providers that have it enabled.

The CLI alternative for scripting:

purple sync                     # sync all providers
purple sync digitalocean        # sync single provider
purple sync --dry-run           # preview changes without writing
purple sync --remove            # remove hosts deleted from provider

Auto-sync

Auto-sync runs on startup for providers that have it enabled. Default is on for all providers except Proxmox (which defaults to off since self-signed TLS and local networks make unattended sync less reliable). You can toggle auto-sync per provider in the TUI provider form or via the CLI:

purple provider add digitalocean --token TOKEN --no-auto-sync   # disable
purple provider add digitalocean --token TOKEN --auto-sync      # re-enable

Provider metadata

Provider metadata (server details like region, instance type and OS) is stored as # purple:meta key=value,key=value comments in your SSH config. The detail panel (press v to toggle) displays these under the provider name heading. Metadata keys match provider terminology (e.g. AWS uses "instance" for instance type, GCP uses "machine" for machine type). Each provider pushes different metadata fields:

Provider Metadata fields
AWS EC2 region, instance, os, status
Azure region, vm_size, image, status
DigitalOcean region, size, image, status
GCP zone, machine, os, status
Hetzner location, type, image, status
i3D.net (dedicated) type, specs
i3D.net (FlexMetal) location, type, os, status
Leaseweb (dedicated) location, specs, status
Leaseweb (cloud) region, type, image, status
Linode region, plan, image, status
OCI region, shape, os, status
OVHcloud region, type, image, status
Proxmox VE node, type, specs, os, status
Scaleway zone, type, image, status
Tailscale os, status
TransIP zone, plan, os, status
UpCloud zone, plan, image, status
Vultr region, plan, os, status

Provider tags

Cloud provider tags and labels are synced into # purple:provider_tags comments. These are always replaced on sync to match the remote exactly. Your own tags in # purple:tags are never touched by sync.

Stale hosts

When a provider no longer returns a host (e.g. a VM was deleted), the host is marked stale instead of being silently kept or hard-deleted.

  • Stale hosts appear dimmed in the host list and sort to the bottom
  • Press X to purge stale hosts (shows host names before deletion)
  • Per-provider purge from the provider list
  • Stale hosts automatically clear when they reappear in the next sync
  • Partial sync failures suppress stale marking to prevent false positives
  • Editing a stale host clears the stale marker on save
  • Filter with tag:stale (fuzzy) or tag=stale (exact)

Managing providers

In the TUI provider list: d to remove a provider, X to purge stale hosts for the selected provider. The provider list is sorted by last sync time.

CLI alternative:

purple provider list                # list configured providers
purple provider remove digitalocean # remove provider

Provider-specific details

AWS EC2

Multi-region sync. AMI names (Amazon Machine Image, the template used to create the instance) resolved for OS metadata. Tags synced (excluding internal aws:* tags). SigV4 request signing (AWS's authentication protocol that signs every HTTP request with your credentials).

Authentication options:

  • --profile default reads ~/.aws/credentials
  • --token AKID:SECRET for inline credentials
  • Falls back to AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars

Region selection: TUI shows a region picker with geographic grouping. CLI uses --regions us-east-1,eu-west-1.

Azure

Multi-subscription sync via the Azure Resource Manager API. Batch IP resolution (3 list calls per subscription: VMs, NICs, Public IPs).

Authentication:

  • Service principal JSON file. Supports both az CLI format (appId/password/tenant) and portal format (clientId/clientSecret/tenantId)
  • Raw Bearer token (e.g. from az account get-access-token)

Subscriptions: passed via --regions SUBSCRIPTION_ID_1,SUBSCRIPTION_ID_2.

VM tags are synced as host tags.

DigitalOcean

Personal access token. Page pagination.

purple provider add digitalocean --token YOUR_TOKEN

GCP (Compute Engine)

Multi-zone sync via the aggregatedList API (a single GCP API call that returns instances from all zones at once). Empty zone filter syncs all zones.

Authentication:

  • Service account JSON key file (purple creates a JWT (JSON Web Token) signed with RS256 (RSA + SHA-256) and exchanges it for an OAuth2 access token. Scope: compute.readonly)
  • Raw access token (e.g. from gcloud auth print-access-token)

Requires a GCP project ID via --project. Network tags and labels synced.

purple provider add gcp --token /path/to/sa-key.json --project my-project --regions us-central1-a

Hetzner

API token. Page pagination. Labels synced as tags.

purple provider add hetzner --token YOUR_TOKEN

Linode (Akamai)

API token. Page pagination. Private IPs filtered.

purple provider add linode --token YOUR_TOKEN

Oracle Cloud Infrastructure (OCI)

Multi-region sync. Reads ~/.oci/config (the standard OCI CLI configuration file containing your tenancy, user and key path) for authentication. RSA-SHA256 HTTP Signature request signing (OCI's authentication method where each HTTP request is signed with your private RSA key).

Compartment sync: Recursive. Point at a tenancy or compartment OCID and all sub-compartments are included automatically.

Required IAM policy:

  • read instance-family in tenancy
  • read virtual-network-family in tenancy
  • inspect compartments in tenancy

Freeform tags synced (defined_tags ignored).

purple provider add oracle --token ~/.oci/config --compartment ocid1.compartment.oc1..aaa --regions eu-amsterdam-1

OVHcloud

OVH Public Cloud instances. Multi-region sync via the OVH API.

Authentication:

  1. Create API credentials at https://eu.api.ovh.com/createApp (or ca/us equivalent)
  2. Generate a consumer key with read access to /cloud/project/*
  3. Find your Public Cloud project ID in the OVH control panel

Token format: app_key:app_secret:consumer_key (colon-separated).

purple provider add ovh --token APP_KEY:APP_SECRET:CONSUMER_KEY --project PROJECT_ID

In the TUI, press Space on the Endpoint field to pick EU, CA or US (defaults to EU).

Metadata synced: region, type (flavor), image, status.

i3D.net

Dedicated/game servers and FlexMetal on-demand bare metal. Both product lines are synced in a single operation.

Authentication:

  1. Generate an API key at https://customer.i3d.net (Profile > API Keys)
  2. Optionally restrict the key to specific IP ranges
purple provider add i3d --token YOUR_API_KEY

Dedicated servers use host- prefix for IDs, FlexMetal uses flex- prefix. Dedicated server metadata includes category and CPU specs. FlexMetal metadata includes location, instance type, OS and status. FlexMetal tags are synced as provider tags.

TransIP

TransIP VPS instances. Supports two authentication methods.

Option 1: RSA Private Key (recommended)

  1. Generate API credentials in the TransIP control panel (Account > API)
  2. Download the RSA private key file
  3. Use format LOGIN:/path/to/private.key

Option 2: Pre-generated Bearer Token

  1. Generate a token in the TransIP control panel
  2. Use the token directly

CLI:

purple provider add transip --token LOGIN:~/.transip/key.pem
# or with pre-generated token:
purple provider add transip --token YOUR_BEARER_TOKEN

Native VPS tags are synced as provider tags.

Leaseweb

Dedicated servers and public cloud instances. Both product lines are synced in a single operation.

Authentication:

  1. Generate an API key at https://secure.leaseweb.com/api-client-management/ 
purple provider add leaseweb --token YOUR_API_KEY

Dedicated servers use bm- prefix for IDs, cloud instances use cloud- prefix. Dedicated server metadata includes location (datacenter site), specs (CPU and RAM) and delivery status. Cloud instance metadata includes region, instance type, OS image and state.

Proxmox VE

Syncs QEMU VMs and LXC containers. VMs with QEMU guest agent installed show actual OS info (e.g. "Debian GNU/Linux 13 (trixie)") instead of generic kernel version. Guest agent and LXC interface detection for IP resolution.

Requirements:

  • URL must start with https:// (validated)
  • --no-verify-tls for self-signed certificates
  • Auto-sync disabled by default
purple provider add proxmox --url https://pve:8006 --token user@pam!token=secret
purple provider add proxmox --url https://pve:8006 --token TOKEN --no-verify-tls

Scaleway

Multi-zone sync across Paris, Amsterdam, Warsaw and Milan (10 zones total).

purple provider add scaleway --token YOUR_TOKEN --regions fr-par-1,nl-ams-1

Tailscale

Dual mode:

  • Without a token: uses local tailscale status --json CLI (peers only, excludes self-node)
  • With a token: uses the Tailscale HTTP API

API keys (tskey-api-*) use HTTP Basic auth. OAuth tokens use Bearer auth. Tags synced (tag: prefix stripped). IPv4 (100.x) preferred over IPv6.

purple provider add tailscale                            # local CLI
purple provider add tailscale --token tskey-api-YOUR_KEY # API

UpCloud

API token. Offset pagination with N+1 detail requests.

purple provider add upcloud --token YOUR_TOKEN

Vultr

API token. Cursor pagination.

purple provider add vultr --token YOUR_TOKEN

Getting started

Features

Reference

Clone this wiki locally