crypticani/torvix repository overview

⁠Torvix

Torvix is an open-source FinOps platform for cloud cost visibility, anomaly detection, forecasting, and unused-resource detection across cloud providers.

Torvix helps engineering, DevOps, SRE, and platform teams understand where cloud spend is going, detect unusual cost spikes, identify hidden waste, and surface optimization opportunities before they impact the bill.

⁠Source Code

GitHub repository:

https://github.com/crypticani/torvix⁠

Docker image:

https://hub.docker.com/r/crypticani/torvix⁠

⁠Key Features

• Multi-cloud cost visibility
• Cloud spend anomaly detection
• Cost forecasting and trend analysis
• Unused and underutilized resource detection
• Region, compartment/account, and service-level drilldowns
• Waste findings with estimated monthly savings
• Prometheus metrics for operational monitoring
• Grafana-compatible dashboards
• API-first architecture for automation and integrations
• Built for FinOps, DevOps, SRE, and platform engineering teams

⁠Use Cases

Torvix helps answer questions like:

• Which region is generating the highest cost?
• Which compartment, account, project, or environment is driving spend?
• Which services are contributing most to the bill?
• Are there sudden cost anomalies?
• Are detached volumes, idle resources, or unused assets still consuming money?
• What resources should be reviewed first for cost optimization?
• How much estimated monthly waste can be reduced?

⁠Architecture

Torvix is designed around separate collectors and analysis engines:

• Cost Collector — ingests cloud billing and usage data
• Inventory Collector — syncs live cloud resource metadata
• Metrics Collector — collects utilization signals for idle-resource detection
• Anomaly Engine — detects abnormal spend patterns
• Waste Detector — identifies possible unused or underutilized resources
• API Service — exposes cost, anomaly, and waste data for dashboards and integrations
• Grafana Dashboards — visualize cost trends, anomalies, and waste findings

⁠Docker Compose Example

Below is a sample docker-compose.yml for running Torvix with PostgreSQL/TimescaleDB, Prometheus, and Grafana.

services:
  torvix-api:
    image: crypticani/torvix:latest
    container_name: torvix-api
    restart: unless-stopped
    depends_on:
      - torvix-postgres
    ports:
      - "8080:8080"
    environment:
      TORVIX_ENV: production
      TORVIX_API_HOST: 0.0.0.0
      TORVIX_API_PORT: 8080

      TORVIX_DB_HOST: torvix-postgres
      TORVIX_DB_PORT: 5432
      TORVIX_DB_NAME: torvix
      TORVIX_DB_USER: torvix
      TORVIX_DB_PASSWORD: change-this-password
      TORVIX_DB_SSLMODE: disable

      TORVIX_DEFAULT_PROVIDER: oci
      TORVIX_RETENTION_DAYS: 90
      TORVIX_COMPRESSION_AFTER_DAYS: 7

      # OCI configuration
      OCI_REGION: ap-mumbai-1
      OCI_TENANCY_OCID: ocid1.tenancy.oc1..example
      OCI_USER_OCID: ocid1.user.oc1..example
      OCI_FINGERPRINT: your-api-key-fingerprint
      OCI_PRIVATE_KEY_PATH: /app/.oci/oci_api_key.pem
      OCI_COMPARTMENT_OCID: ocid1.compartment.oc1..example
      OCI_COST_BUCKET_NAME: your-cost-report-bucket
      OCI_COST_NAMESPACE: your-object-storage-namespace
    volumes:
      - ./oci:/app/.oci:ro
    networks:
      - torvix

  torvix-postgres:
    image: timescale/timescaledb:latest-pg18
    container_name: torvix-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: torvix
      POSTGRES_USER: torvix
      POSTGRES_PASSWORD: change-this-password
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    networks:
      - torvix

  prometheus:
    image: prom/prometheus:latest
    container_name: torvix-prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./data/prometheus:/prometheus
    networks:
      - torvix

  grafana:
    image: grafana/grafana-oss:latest
    container_name: torvix-grafana
    restart: unless-stopped
    depends_on:
      - prometheus
      - torvix-api
    ports:
      - "3000:3000"
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: change-this-password
    volumes:
      - ./data/grafana:/var/lib/grafana
    networks:
      - torvix

networks:
  torvix:
    driver: bridge

⁠Prometheus Configuration

Create a prometheus.yml file in the same directory as your compose file:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: torvix-api
    metrics_path: /metrics
    static_configs:
      - targets:
          - torvix-api:8080

⁠Installation

Create a project directory:

mkdir torvix
cd torvix

Create the required directories:

mkdir -p data/postgres data/prometheus data/grafana oci

Create the Docker Compose file:

nano docker-compose.yml

Paste the compose file shown above.

Create the Prometheus configuration file:

nano prometheus.yml

Paste the Prometheus configuration shown above.

Place your OCI API private key inside the oci directory:

cp /path/to/oci_api_key.pem ./oci/oci_api_key.pem
chmod 600 ./oci/oci_api_key.pem

Update the OCI environment variables in docker-compose.yml:

OCI_REGION: ap-mumbai-1
OCI_TENANCY_OCID: your-tenancy-ocid
OCI_USER_OCID: your-user-ocid
OCI_FINGERPRINT: your-api-key-fingerprint
OCI_PRIVATE_KEY_PATH: /app/.oci/oci_api_key.pem
OCI_COMPARTMENT_OCID: your-compartment-ocid
OCI_COST_BUCKET_NAME: your-cost-report-bucket
OCI_COST_NAMESPACE: your-object-storage-namespace

Start Torvix:

docker compose up -d

Check container status:

docker compose ps

View Torvix logs:

docker compose logs -f torvix-api

Stop Torvix:

docker compose down

⁠Usage

Once running, access the services:

• Torvix API: http://localhost:8080
• Torvix Metrics: http://localhost:8080/metrics
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000

Default Grafana login from the compose example:

Username: admin
Password: change-this-password

Change the Grafana password before using this in production.

⁠API Examples

Health check:

curl http://localhost:8080/health

Metrics endpoint:

curl http://localhost:8080/metrics

Dashboard overview:

curl "http://localhost:8080/api/v1/dashboard/overview?provider=oci"

Cost by region:

curl "http://localhost:8080/api/v1/dashboard/cost-by-region?provider=oci"

Cost by compartment:

curl "http://localhost:8080/api/v1/dashboard/cost-by-compartment?provider=oci&limit=15"

Cost by service:

curl "http://localhost:8080/api/v1/dashboard/cost-by-service?provider=oci"

Cost anomalies:

curl "http://localhost:8080/api/v1/dashboard/anomalies?provider=oci"

Ingestion status:

curl "http://localhost:8080/api/v1/dashboard/ingestion-status"

Waste findings:

curl "http://localhost:8080/api/v1/waste/findings?provider=oci"

Waste summary:

curl "http://localhost:8080/api/v1/waste/summary?provider=oci"

⁠Using an Existing PostgreSQL Database

If you already have PostgreSQL or TimescaleDB running separately, remove the torvix-postgres service from the compose file and point Torvix to your existing database:

environment:
  TORVIX_DB_HOST: your-postgres-host
  TORVIX_DB_PORT: 5432
  TORVIX_DB_NAME: torvix
  TORVIX_DB_USER: torvix
  TORVIX_DB_PASSWORD: your-password
  TORVIX_DB_SSLMODE: disable

Example with PostgreSQL running on the Docker host:

environment:
  TORVIX_DB_HOST: host.docker.internal
  TORVIX_DB_PORT: 5432
  TORVIX_DB_NAME: torvix
  TORVIX_DB_USER: torvix
  TORVIX_DB_PASSWORD: your-password
  TORVIX_DB_SSLMODE: disable

For Linux hosts, you may need to add:

extra_hosts:
  - "host.docker.internal:host-gateway"

⁠Environment Variables

Common Torvix variables:

OCI-specific variables:

⁠Data Retention

The sample configuration uses:

TORVIX_RETENTION_DAYS=90
TORVIX_COMPRESSION_AFTER_DAYS=7

This means Torvix keeps cost and analytics data for 90 days and can compress older records after 7 days when TimescaleDB compression is enabled.

⁠Volumes

The sample compose file uses bind mounts:

./data/postgres    → PostgreSQL / TimescaleDB data
./data/prometheus  → Prometheus data
./data/grafana     → Grafana data
./oci              → OCI API key directory

For production deployments, back up these directories regularly and restrict file permissions.

⁠Grafana Setup

After starting the stack, open Grafana:

http://localhost:3000

Add Prometheus as a data source:

URL: http://prometheus:9090

If Torvix provides Grafana dashboard JSON files, import them from the Torvix repository.

Recommended dashboard sections:

• Cost overview
• Cost by region
• Cost by compartment/account/project
• Cost by service
• Anomaly findings
• Ingestion status
• Waste findings
• Estimated monthly waste

⁠Upgrade Notes

CloudPulse has been renamed to Torvix.

Existing deployments may still use older database names or environment variables for compatibility, but new deployments should use the Torvix naming convention and TORVIX_* environment variables.

Recommended new naming:

cloudpulse-api       → torvix-api
cloudpulse-worker    → torvix-worker
cloudpulse-collector → torvix-collector
cloudpulse-ui        → torvix-ui
CloudPulseAPI        → TorvixAPI
CLOUDPULSE_*         → TORVIX_*

If you are upgrading from an older CloudPulse deployment, review your compose service names, database name, environment variables, dashboards, and datasource names before upgrading.

⁠Security Notes

• Do not commit OCI private keys to Git.
• Use strong database and Grafana passwords.
• Restrict access to the Torvix API if exposing it publicly.
• Use HTTPS behind a reverse proxy such as Nginx, Caddy, or Traefik.
• Mount cloud credentials as read-only whenever possible.
• Rotate cloud API keys periodically.
• Avoid exposing PostgreSQL, Prometheus, or Grafana directly to the public internet without authentication and network restrictions.

⁠Example Production Reverse Proxy

Torvix can be placed behind Nginx, Caddy, Traefik, or any other reverse proxy.

Example API endpoint:

https://torvix.example.com

Recommended public exposure:

Torvix API   → behind HTTPS and authentication/network allowlist
Grafana      → behind HTTPS and strong authentication
Prometheus   → private only
PostgreSQL   → private only

⁠Project Links

• GitHub: https://github.com/crypticani/torvix⁠
• Docker Hub: https://hub.docker.com/r/crypticani/torvix⁠

⁠License

Torvix is open-source. See the GitHub repository for license details.