Building a Homelab Agent: Connecting Android to My Server
Most people track personal expenses in one of two ways:
- Manually typing every coffee and grocery receipt into an app or spreadsheet (which you inevitably abandon after three weeks).
- Installing commercial expense tracker apps that demand full
READ_SMSpermissions and upload your bank transactions, account balances, and merchant records to third-party marketing and advertising servers.
I didn’t want either.
In India, every bank transaction, UPI payment, and debit card charge generates an instant SMS notification. The data is already there on your phone. What was missing was a secure, private bridge to transport those messages directly into my self-hosted financial ledger (Prabandh) without touching a third-party cloud.
So I built a two-part system: Home Agent (Android) and Home Agent (Backend).
The System Architecture
┌──────────────────────────────────────────────┐
│ Android Phone (Home Agent App) │
│ 1. Receives incoming bank/transaction SMS │
│ 2. Extracts sender, timestamp, and body │
│ 3. Encrypts payload & attaches API key │
└──────────────────────┬───────────────────────┘
│ HTTPS POST over LAN (or WireGuard)
▼
┌──────────────────────────────────────────────┐
│ Home Agent Backend (FastAPI / Python 3.13) │
│ - Verifies mandatory shared API_KEY │
│ - Parses transaction amounts & merchants │
│ - Stores raw log in SQLite/MariaDB │
└──────────────────────┬───────────────────────┘
│ POST /api/v1/platform/sms/ingest
▼
┌──────────────────────────────────────────────┐
│ Self-Hosted Financial Ledger (Prabandh) │
│ - Automatically categorizes transaction │
│ - Updates balance and monthly budgets │
└──────────────────────────────────────────────┘
1. The Android Client (home-agent-android)
The mobile client is a lightweight native Android app:
- BroadcastReceiver: Listens for the
SMS_RECEIVEDaction. - Filter Rules: The app only triggers on registered bank sender codes (e.g.,
HDFCBK,SBIINB,AXISBK). Personal messages from friends or family are discarded on-device and never processed. - Network Dispatcher: When a valid transaction message arrives, the app forms a JSON payload and dispatches an HTTP POST request to the local backend listener.
- Offline Resiliency: If I’m outside the house and not connected to home Wi-Fi or my WireGuard VPN, the app enqueues the extracted payload into an encrypted Room database and flushes the queue as soon as connection to the homelab is restored.
2. The FastAPI Listener (home-agent-backend)
The receiver on the homelab side is a lightweight FastAPI service written in Python:
# app/main.py (Simplified)
from fastapi import FastAPI, Header, HTTPException, status
import os
app = FastAPI(title="Home Agent Listener")
SHARED_SECRET = os.getenv("API_KEY")
@app.post("/api/sms")
async def receive_sms(payload: SMSPayload, x_api_key: str = Header(...)):
if not SHARED_SECRET or x_api_key != SHARED_SECRET:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Unauthorized agent request"
)
# Forward payload to financial ledger platform for ingestion
return await ingest_transaction(payload)
Security Considerations:
- Mandatory Shared Secret: If
API_KEYis not present in.env, the entire API returns503 Service Unavailable. No routes accept unauthenticated calls. - LAN-Only Binding: The service runs behind Traefik inside the internal server VLAN (
10.0.20.0/24). It is never exposed directly to the public internet without passing through Authelia or an authenticated VPN.
Why This Beats Commercial SaaS
- Absolute Privacy: Financial records and account numbers remain strictly on physical storage drives inside my house.
- Zero Manual Entry: Expenses show up on my self-hosted financial dashboard within 2 seconds of swiping a card or making a UPI payment.
- Extensibility: Once the pipeline was working, I added custom triggers: certain smart home notifications and server alerts can now be routed bidirectionally between my phone and the homelab.
Key Takeaway
Smartphones are the ultimate sensor in a smart home and homelab ecosystem. Instead of relying on closed commercial cloud apps to bridge phone telemetry to your server, a 100-line FastAPI listener and a small Kotlin client give you complete control over your personal data.