REST API for the SOFE FinOps Engine
Multi-tenant evaluation platform with catalog, history, and alerts.

Quick Start · Endpoints · Usage · Ecosystem

---

Wraps the SOFE Python engine in a FastAPI application, enabling HTTP-based evaluations.

pip install sofe sofe-server
sofe-server
# → http://localhost:8080

Quick Start

# Install
pip install sofe sofe-server
# Start server
sofe-server
# Evaluate your AWS account
curl -X POST http://localhost:8080/evaluate \
-H "Content-Type: application/json" \
-d '{"aws_profile": "default"}'

Or use the Go CLI:

sofe serve # starts sofe-server in background
sofe evaluate # calls localhost:8080/evaluate

Endpoints

Method	Path	Description
GET	/health	Health check
POST	/evaluate	Evaluate AWS account against policies
POST	/validate	Validate an Architecture Graph (BYaML v0.4 JSON)
GET	/policies	List all loaded policies
GET	/collectors	List available collectors
GET	/metrics	List metrics per collector
POST	/connect/test	Test STS AssumeRole connection

Usage

Evaluate with cross-account role

curl -X POST http://localhost:8080/evaluate \
-H "Content-Type: application/json" \
-d '{ "role_arn": "arn:aws:iam::123456789012:role/SOFEReadOnlyRole", "external_id": "sofe-abc123" }'

List policies

curl http://localhost:8080/policies

Docker

docker run -p 8080:8080 -v ~/.aws:/root/.aws:ro \
ghcr.io/breakingthecloud/sofe-community:latest

Architecture

sofe-server (this repo)
│
│ imports
▼
sofe/ (engine — pip install sofe)
│
│ boto3
▼
Your AWS Account (read-only)

sofe-server is a thin wrapper — all policy evaluation logic lives in the sofe engine.

Requirements

• Python 3.11+
• sofe >= 0.2.0 (engine)
• AWS credentials (profile or role)

Development

git clone https://github.com/breakingthecloud/sofe-server.git
cd sofe-server
uv venv &&source .venv/bin/activate
uv pip install -e ".[dev]" -e ../sofe/
uvicorn sofe_server.app:app --reload --port 8080

Ecosystem

Project	Description
sofe	Python engine (collectors + policies)
sofe-cli	Go CLI (19 commands, TUI)
sofe-action	GitHub Action for CI/CD
platform.sofe.dev	SaaS dashboard (free tier)
sofe.dev/docs	Documentation (26 pages)

License

Apache 2.0 — see LICENSE.

---

sofe.dev · Engine · finoptix.dev