falcon-system-service

Python FastAPI backend daemon for FalconOS. Runs as a systemd service via uvicorn on localhost:8000. Bridges the React launcher UI with the underlying Linux system.

Stack

Technology	Purpose
Python 3.12	Primary language
FastAPI	REST API framework
uvicorn	ASGI server
vdf	Steam VDF file parser
psutil	RAM and CPU stats
requests	SteamGridDB cover art fetching
sqlite3	Lutris database reader

Directory structure

falcon-system-service/
├── main.py                  # FastAPI app entry point
├── routers/
│   ├── games.py             # GET /games
│   ├── stats.py             # GET /stats
│   ├── launch.py            # POST /launch/{id}
│   └── system.py            # POST /system/reboot, /desktop, /shutdown
├── services/
│   ├── steam.py             # Steam VDF library parser
│   ├── lutris.py            # Lutris SQLite DB reader
│   ├── steamgriddb.py       # Cover art fetcher (cached)
│   ├── nvidia.py            # nvidia-smi subprocess wrapper
│   └── system.py            # Reboot, shutdown, desktop switch
├── requirements.txt
└── falcon-service.service   # systemd unit file

API reference

GET  /games              → list of installed games with cover art and ProtonDB rating
GET  /stats              → GPU temp, RAM used/total, current FPS
POST /launch/{id}        → launch game via Steam or Lutris CLI
POST /system/desktop     → exit Gamescope, start KDE Plasma
POST /system/reboot      → reboot the machine
POST /system/shutdown    → shut down the machine

Example responses

// GET /games
[
  {
    "id": "271590",
    "name": "Grand Theft Auto V",
    "coverArt": "https://cdn.steamgriddb.com/...",
    "protonRating": "platinum",
    "lastPlayed": 1716739200,
    "source": "steam"
  }
]

// GET /stats
{
  "gpu": { "temp": 68, "usage": 74 },
  "ram": { "used": 9.2, "total": 16.0 },
  "fps": 60
}

Development

git clone https://github.com/FalconGamingOS/falcon-system-service
cd falcon-system-service
pip install -r requirements.txt
uvicorn main:app --host localhost --port 8000 --reload

Systemd service

# falcon-service.service
[Unit]
Description=FalconOS System Service
After=network.target

[Service]
ExecStart=/usr/bin/uvicorn main:app --host localhost --port 8000
WorkingDirectory=/opt/falcon/system-service
Restart=always
User=gamer

[Install]
WantedBy=multi-user.target

sudo systemctl enable falcon-service
sudo systemctl start falcon-service

Requirements

fastapi
uvicorn
vdf
requests
psutil

License

GPL v3.0