Forem: [Tanwydd]

Building a Self-Hosted Bot Management Platform with Docker, FastAPI and React

[Tanwydd] — Wed, 15 Apr 2026 19:25:46 +0000

Managing more than two or three automated scripts in production is where things get messy. You end up with a collection of Python files scattered across servers, credentials hardcoded or stored in plaintext somewhere, no visibility into what's running or failing, and deployments that require SSH access and manual intervention.

I built BotFarm to solve this. It's a self-hosted platform that lets you create, deploy, monitor and maintain containerized Python bots from a web dashboard — no SSH required.

The problem with ad-hoc bot management

The typical evolution of a bot infrastructure goes like this:

You write a script. It works. You add another. Then five more. At some point you have fifteen scripts running on a server, some as cron jobs, some as systemd services, some launched manually. Credentials are in config files with 644 permissions. Logs go to files that nobody reads until something breaks. Deploying a new version means SSHing in, pulling the repo, restarting the service, and hoping nothing else broke.

This is fine for personal projects. It's not fine when other developers need to deploy and manage their own bots, when you need an audit trail, or when credentials need to be kept secure.

BotFarm replaces all of that with a centralized dashboard.

Architecture

Every bot runs in its own Docker container with resource limits (512MB RAM, 0.5 CPUs by default). The dashboard never touches the Docker socket directly — all container operations go through tecnativa/docker-socket-proxy, which exposes only the operations the dashboard actually needs.

  Internet
      │
      ▼  :80 / :443
  ┌──────────────┐
  │    Nginx     │  TLS · reverse proxy · static assets
  └──────┬───────┘
         │  :8080 (internal)
         ▼
  ┌──────────────────┐         ┌───────────────────────┐
  │  Dashboard       │─────────▶  Docker Socket Proxy │
  │  FastAPI + React │  :2375  │  (allowlist only)     │
  └──────┬───────────┘ internal└──────────┬────────────┘
         │                                │  /var/run/docker.sock
         │  :3306 (internal)              ▼
         ▼                        Docker Engine
  ┌─────────────┐                         │
  │   MariaDB   │          ┌──────────────┼──────────────┐
  └─────────────┘       bot-a           bot-b           bot-n
                        [512MB]         [512MB]         [512MB]
                        [0.5CPU]        [0.5CPU]        [0.5CPU]

The Docker Socket Proxy is not optional — it's the architectural decision that makes this safe to run in a multi-developer environment. Without it, a compromised dashboard container has full control over the Docker daemon. With it, the blast radius is contained to the allowlisted operations: CONTAINERS, IMAGES, BUILD, NETWORKS.

Credential management

Storing bot credentials is the part most people get wrong. Plaintext in environment files, base64-encoded strings passed as environment variables, secrets committed to git — all of these are real patterns I've seen in production.

BotFarm encrypts all credentials with AES-256-GCM before storing them in the database. Each encryption operation uses a random IV, so the same plaintext produces a different ciphertext every time. The master key lives in /etc/botfarm.env with 600 permissions, generated at install time and never touched again.

import os
import base64
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

def encrypt(plaintext: str, master_key: bytes) -> str:
    iv = os.urandom(12)  # 96-bit random IV per encryption
    aesgcm = AESGCM(master_key)
    ciphertext = aesgcm.encrypt(iv, plaintext.encode(), None)
    # Store IV + ciphertext together
    return base64.b64encode(iv + ciphertext).decode()

def decrypt(encrypted: str, master_key: bytes) -> str:
    data = base64.b64decode(encrypted)
    iv, ciphertext = data[:12], data[12:]
    aesgcm = AESGCM(master_key)
    return aesgcm.decrypt(iv, ciphertext, None).decode()

At runtime, decrypted credentials are injected into each bot container as environment variables — they exist in memory during execution and are never written to disk.

Real-time log streaming via WebSocket

One of the more interesting technical problems was streaming container logs to the browser in real time. The naive approach — polling a REST endpoint every few seconds — introduces latency and hammers the database unnecessarily.

The solution is a WebSocket endpoint that reads directly from the Docker container's log stream:

@router.websocket("/ws/logs/{bot_id}")
async def stream_logs(websocket: WebSocket, bot_id: int):
    await websocket.accept()
    try:
        container = docker_client.containers.get(f"bot_{bot_id}")
        for log_line in container.logs(stream=True, follow=True, tail=50):
            await websocket.send_text(log_line.decode().strip())
    except Exception as exc:
        await websocket.send_text(f"Stream error: {exc}")
    finally:
        await websocket.close()

The same pattern applies to build logs — when you deploy a new version of a bot, the Docker image build output streams directly to the browser line by line via a separate WebSocket endpoint.

Bot versioning with visual diff

Every time you save a new version of a bot's code, BotFarm stores the previous version and generates a diff. From the dashboard you can see the full history, compare any two versions side by side, and roll back to any previous version in one click.

The code editor is Monaco — the same editor that powers VS Code — embedded directly in the dashboard. You get syntax highlighting, autocomplete and error detection without leaving the browser.

Writing a bot

Bots are standard Python scripts with access to bot_logger, a shared library that handles logging and metrics:

import os
import json
from bot_logger import BotLogger

logger = BotLogger()

try:
    creds = json.loads(os.environ.get("BOT_CREDENTIALS", "{}"))
    logger.log("INFO", "Bot started")

    records = process_data(creds)

    logger.log("INFO", f"Cycle complete: {records} records processed")
    logger.metric("records_processed", records)

finally:
    logger.close(exit_code=0)

The finally block is important — logger.close() writes the final execution status to the database and releases resources. If it doesn't run, the dashboard shows the bot as still running.

Security model

A few decisions worth explaining:

JWT with automatic refresh. Tokens expire after one hour. The frontend automatically refreshes at the 50-minute mark without interrupting the user's session. On logout, the token's JTI is revoked in the database — subsequent requests with that token are rejected even if it hasn't expired.

Rate limiting on login. Ten attempts per minute per IP using slowapi. After that, requests are rejected with 429 until the window resets. Simple, effective, no CAPTCHA complexity.

Audit log as append-only. The database user that the application uses (botfarm_app) has INSERT and SELECT on the audit log table — never UPDATE or DELETE. This is enforced at the database privilege level, not just in application code. An audit log you can delete is not an audit log.

bcrypt with cost 12. Slow enough to make brute force impractical, fast enough that legitimate logins don't feel slow on modern hardware.

The stack

Layer	Technology
Backend	FastAPI 0.115 · Python 3.12 · Uvicorn
Frontend	React 18 · Vite · Chart.js · Monaco Editor
Database	MariaDB 11
Containers	Docker Engine · Docker Compose v2
Proxy	Nginx (TLS 1.2/1.3)
Docker security	tecnativa/docker-socket-proxy
Encryption	AES-256-GCM · bcrypt · JWT HS256
Platform	AlmaLinux 10 LTS

What it doesn't do

BotFarm is infrastructure for managing bots, not a scraping framework. It doesn't handle proxy rotation, browser automation, or anti-detection. Those concerns live in the bot code itself — BotFarm just provides the container to run it in, the credentials to authenticate with, and the visibility to know when something breaks.

Detecting Deepfake Audio in Python: Why the Threshold Matters More Than the Model

[Tanwydd] — Sun, 12 Apr 2026 11:32:00 +0000

Cloning a voice used to require a recording studio and a professional impersonator. Today it takes a few seconds of audio and a free API call.

That changes the threat model for any system that verifies identity by voice.

The problem with voice verification in 2026

Voice biometrics have been used in contact centers and banking for years. The assumption was that a voice is hard to fake — you either sound like someone or you don't, and training a model to tell the difference was expensive enough to deter casual fraud.

That assumption is gone. Modern voice cloning tools can reproduce a speaker's voice with enough fidelity to fool both humans and many biometric systems, using as little as three to five seconds of target audio. The barrier is now effectively zero for anyone motivated enough to try.

The response can't just be "better biometrics." It has to include detection of synthetic audio alongside speaker verification.

Two problems, two models

VoiceID Compare solves both problems in a single API call:

Speaker verification — do these two audio samples belong to the same person?
Deepfake detection — was either sample generated by AI?

These are separate tasks that require separate models. Confusing them is a common mistake — a deepfake detector doesn't tell you if two voices match, and a speaker verification model doesn't tell you if the audio is synthetic.

Speaker verification: embeddings and cosine similarity

The speaker verification component uses SpeechBrain's ResNet model, trained on VoxCeleb — a large-scale dataset of celebrity speech collected from YouTube.

The model doesn't compare audio files directly. It converts each audio sample into an embedding — a vector of floating point numbers that represents the speaker's vocal characteristics in a high-dimensional space.

from speechbrain.inference.speaker import SpeakerRecognition

model = SpeakerRecognition.from_hparams(
    source="speechbrain/spkrec-resnet-voxceleb"
)

score, prediction = model.verify_files(audio_path_1, audio_path_2)

The similarity between two embeddings is calculated using cosine similarity — the angle between the two vectors in that high-dimensional space. Vectors pointing in the same direction (same speaker) have high cosine similarity. Vectors pointing in different directions (different speakers) have low similarity.

The raw score is normalized to a 0-100 percentage scale for human readability.

Why audio preprocessing matters

Raw audio files from real-world sources are messy. Different sample rates, different channel counts, different durations, background noise. Feeding inconsistent audio to the model produces unreliable results.

Before embedding extraction, every audio file goes through normalization:

import torchaudio

def preprocess_audio(path: str):
    waveform, sample_rate = torchaudio.load(path)

    # Convert to mono
    if waveform.shape[0] > 1:
        waveform = waveform.mean(dim=0, keepdim=True)

    # Resample to 16kHz (model requirement)
    if sample_rate != 16000:
        resampler = torchaudio.transforms.Resample(sample_rate, 16000)
        waveform = resampler(waveform)

    return waveform

16kHz mono is the format the ResNet model was trained on. Deviating from it degrades accuracy in ways that aren't always obvious — the model still produces an output, it's just less reliable.

Deepfake detection: Wav2Vec2

The deepfake detection component uses a fine-tuned Wav2Vec2 model from HuggingFace, trained to classify audio as real or synthetic.

Wav2Vec2 is a self-supervised model originally designed for speech recognition. The fine-tuned version used here has been trained on a dataset of real and AI-generated speech samples, learning to identify the subtle artifacts that synthetic audio introduces — phase discontinuities, unnatural prosody, artifacts from vocoder processing.

from transformers import pipeline

deepfake_detector = pipeline(
    "audio-classification",
    model="garystafford/wav2vec2-deepfake-voice-detector"
)

result = deepfake_detector(audio_path)
# Returns: [{'label': 'fake', 'score': 0.73}, {'label': 'real', 'score': 0.27}]

The output is a probability score per class. A score of 0.73 for 'fake' means the model is 73% confident the audio was synthetically generated.

The threshold problem

Here's where most implementations go wrong: they treat the model's output as ground truth.

It isn't. It's a probability estimate with a confidence interval that varies depending on audio quality, recording conditions, the specific voice cloning tool used, and how much the model has been updated relative to the latest generation of synthesis tools.

The threshold — the score above which you classify audio as a deepfake — is a design decision, not a model parameter. And it has asymmetric consequences:

Too low (e.g. 40%): high false positive rate. Legitimate users get flagged. Trust collapses.
Too high (e.g. 80%): high false negative rate. Actual deepfakes get through. False confidence.

For forensic use, the threshold needs to be calibrated against your specific threat model and your tolerance for each type of error. The system should surface the raw score, not just a binary verdict.

DEEPFAKE_ALERT_THRESHOLD = 0.60  # tunable per deployment

def interpret_deepfake_score(score: float) -> dict:
    return {
        "score_pct": round(score * 100, 1),
        "alert": score >= DEEPFAKE_ALERT_THRESHOLD,
        "verdict": "possible deepfake" if score >= DEEPFAKE_ALERT_THRESHOLD else "appears genuine",
    }

The 60% default is a starting point, not a recommendation. In a banking compliance context you might want 50%. In a forensic investigation you might want to surface everything above 30% for manual review.

Running both models in parallel

Speaker verification and deepfake detection are independent. Running them in parallel cuts processing time roughly in half.

Since both are CPU/GPU bound, they need to run in a thread pool to avoid blocking an async event loop:

import asyncio
from concurrent.futures import ThreadPoolExecutor

executor = ThreadPoolExecutor(max_workers=2)

async def compare(audio_path_1: str, audio_path_2: str) -> dict:
    loop = asyncio.get_event_loop()

    speaker_task = loop.run_in_executor(
        executor, verify_speaker, audio_path_1, audio_path_2
    )
    deepfake_task = loop.run_in_executor(
        executor, detect_deepfake, audio_path_1
    )

    similarity, deepfake = await asyncio.gather(speaker_task, deepfake_task)

    return {
        "similarity_pct": similarity,
        "audio_1_deepfake": deepfake,
    }

Wrap with asyncio.wait_for — model inference on long audio files can take tens of seconds and you don't want hung requests blocking the server.

The combination that should raise flags

The most dangerous scenario isn't a low similarity score or a high deepfake score in isolation. It's high similarity combined with a high deepfake score.

That means: the voice sounds like the target person, but the audio was probably synthesized. That's a cloning attack.

def interpret_result(similarity_pct: float, deepfake_score: float) -> str:
    if similarity_pct >= 75 and deepfake_score >= 0.60:
        return "HIGH RISK: voice matches but audio may be synthetic — possible cloning attack"
    if similarity_pct >= 75:
        return "same person"
    if similarity_pct >= 55:
        return "inconclusive — manual review recommended"
    return "different people"

This case needs explicit handling in the interpretation logic, not just surfacing both scores independently.

What this doesn't solve

No system catches everything. The current generation of voice cloning tools produces audio that fools both humans and models at rates that should make anyone uncomfortable relying on voice verification as a sole authentication factor.

This is a layer in a defense stack, not a complete solution. Combined with behavioral signals, session context, and human review for edge cases, it raises the cost of a successful attack significantly. Used alone as a binary gate, it will eventually be bypassed.

The honest answer to "is this voice real?" is always a probability, not a fact. The system's job is to surface that probability clearly enough that the humans making decisions can act on it.