mathumathi247/finops-agent

By mathumathi247

•Updated 3 months ago

Public Docker image of Open-source, CLI-first, multi-cloud infrastructure cost reasoning agent.

Image

Networking

Developer tools

Web servers

1.2K

Overview Tags

mathumathi247/finops-agent repository overview

⁠finops-agent

Open-source, CLI-first, multi-cloud infrastructure cost reasoning agent.

Connect to your cloud billing APIs, detect waste, spot anomalies, forecast spend — and get plain-English explanations powered by an LLM of your choice. All without your data ever leaving your machine.

⁠Quick Start

docker pull mathumathi247/finops-agent:latest

docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  -v ~/.aws:/home/finops/.aws:ro \
  mathumathi247/finops-agent:latest \
  collect

Then:

docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  -v ~/.aws:/home/finops/.aws:ro \
  mathumathi247/finops-agent:latest \
  summary

⁠Supported Clouds

Cloud	Cost Data	Resources
AWS	Cost Explorer API	EC2, EBS, RDS, ELB, NAT Gateway, EKS
GCP	BigQuery billing export	Compute VMs, Persistent Disks, LBs, GKE
Azure	Cost Management API	VMs, Managed Disks, LBs, AKS, Storage, App Service
OCI	Usage API	Compute, Block Volumes, LBs, OKE

All four SDKs are included in the image — no separate pulls needed.

⁠Commands

# Collect cost + resource data (last 30 days)
docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  -v ~/.aws:/home/finops/.aws:ro \
  mathumathi247/finops-agent:latest collect

# Cost breakdown by service and region
docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  mathumathi247/finops-agent:latest summary

# AI-powered full bill explanation
docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  mathumathi247/finops-agent:latest explain-bill

# Find idle and unattached resources
docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  mathumathi247/finops-agent:latest find-waste

# Detect and explain cost spikes
docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  mathumathi247/finops-agent:latest explain-spike

# Monthly cost forecast
docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  mathumathi247/finops-agent:latest forecast

⁠Mounting Credentials

Mount only the clouds you use — all read-only:

docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  -v ~/.aws:/home/finops/.aws:ro \                          # AWS
  -v ~/.config/gcloud:/home/finops/.config/gcloud:ro \      # GCP
  -v ~/.azure:/home/finops/.azure:ro \                      # Azure
  -v ~/.oci:/home/finops/.oci:ro \                          # OCI
  mathumathi247/finops-agent:latest summary

The -v ~/.finops-agent mount persists your local SQLite database between runs. Without it, collected data is lost when the container exits.

⁠Shell Alias (recommended)

Add to ~/.bashrc or ~/.zshrc to use it just like the native CLI:

alias finops='docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  -v ~/.aws:/home/finops/.aws:ro \
  -v ~/.config/gcloud:/home/finops/.config/gcloud:ro \
  -v ~/.azure:/home/finops/.azure:ro \
  -v ~/.oci:/home/finops/.oci:ro \
  mathumathi247/finops-agent:latest'

# Then just use:
finops summary
finops find-waste --provider aws
finops explain-bill

⁠CI/CD — GitHub Actions

- name: Collect daily cost data
  run: |
    docker run --rm \
      -v $HOME/.finops-agent:/home/finops/.finops-agent \
      -e AWS_ACCESS_KEY_ID=${{ secrets.AWS_ACCESS_KEY_ID }} \
      -e AWS_SECRET_ACCESS_KEY=${{ secrets.AWS_SECRET_ACCESS_KEY }} \
      mathumathi247/finops-agent:latest collect --provider aws

- name: Find waste
  run: |
    docker run --rm \
      -v $HOME/.finops-agent:/home/finops/.finops-agent \
      mathumathi247/finops-agent:latest find-waste --output json

⁠LLM Configuration (optional)

The LLM is used only to explain already-computed results in plain English. All cost detection and waste analysis runs without one.

docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  mathumathi247/finops-agent:latest \
  config set llm.provider local

docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  mathumathi247/finops-agent:latest \
  config set llm.api_key gsk_your_groq_key

docker run --rm \
  -v ~/.finops-agent:/home/finops/.finops-agent \
  mathumathi247/finops-agent:latest \
  config set llm.base_url https://api.groq.com/openai/v1

Supports: Groq (free tier), Ollama (fully local), OpenAI, Anthropic, Google Gemini.

⁠Security

Read-only cloud access — never calls write, mutate, or delete APIs
Credentials mounted read-only — :ro flag on all credential mounts
Runs as non-root — unprivileged user inside the container
Data stays local — SQLite at ~/.finops-agent/finops.db on your machine
LLM data redaction — account IDs, ARNs, IPs, and credentials stripped before any LLM call
Zero telemetry — nothing phones home

⁠Tags

Tag	Description
`latest`	Most recent stable release
`0.3.0`	Current release — AWS, GCP, Azure, OCI
`0.2.0`	Previous release

Pin to a specific version tag in production and CI pipelines.

⁠Links

GitHub: github.com/mathumathi-v/finops-cloud⁠
Full setup guide: medium.com/@mathumathiv247⁠
License: Apache-2.0

Tag summary

Recent tags

Content type

Image

Digest

sha256:0b2788a44…

Size

267.7 MB

Last updated

3 months ago

docker pull mathumathi247/finops-agent