Speedtape

How to run it.

Mac and Windows setup, and how an AI agent should run and change this tool.

Mac

Homebrew installs the official Ookla CLI. Collectors then live in LaunchAgents.

    What you need
    macOS, Node.js 20+, Homebrew, and the official Ookla Speedtest CLI. The first CLI run may ask you to accept the license. Collectors pass --accept-license and --accept-gdpr so they can run unattended.
    Setup
    From the repo root, run the Mac commands in order. Then open http://localhost:3000 and go to /app. From another device on the same Wi-Fi use http://<this-computer-lan-ip>:3000. The dev server listens on all interfaces.
    After you move the folder
    Run npm run install-agent again so every collector points at the new path. Closing the browser is fine. The computer must stay awake or the job is skipped.
    Plists
    ~/Library/LaunchAgents/com.speedtape.speedtest.<id>.plist
    Login item
    ~/Library/Application Support/speedtape/Speedtape.app
    Logs
    ~/Library/Logs/speedtape.out.log and speedtape.err.log
    Database
    ~/Library/Application Support/speedtape/speedtests.db

    Windows

    Winget installs the CLI. Task Scheduler runs each collector while this computer is awake.

      Visual Studio C++ Build Tools are required so npm can compile better-sqlite3.

      What you need
      Windows, Node.js 20+, Visual Studio C++ Build Tools, and the official Ookla Speedtest CLI. Build Tools are required so npm install can compile better-sqlite3.
      Setup
      From the repo root, run the Windows commands in order. Then open http://localhost:3000 and go to /app. From another device on the same Wi-Fi use http://<this-computer-lan-ip>:3000.
      After you move the folder
      Run npm run install-agent again so every scheduled task points at the new path. Sleeping skips the job. Closing the dashboard does not.
      Tasks
      Speedtape.speedtest.<id> in Task Scheduler
      Logs and database
      %APPDATA%\speedtape\

      AI agents

      Speedtape is a local house record. Change the right files, verify with tests, and leave generated collector jobs alone.

      What the tool is
      A speed record for one computer. The official Ookla CLI writes samples into SQLite on this machine. /app is the dashboard: latest run, 24-hour tape, history, and failed gaps. /app/config adds collectors. /app/runs is the archive and CSV export. The public site in docs/ is GitHub Pages only. It is not the dashboard.
      How the pieces connect
      app/page.tsx is the local landing. docs/index.html and docs/docs.html are the Pages copies. Keep landing copy and structure in sync. Dashboard routes live under app/app/. lib/ owns the database, schedules, speedtest CLI, and paths. scripts/ owns npm run speedtest, install-agent, and uninstall-agent. Collectors are OS jobs (launchd on Mac, Task Scheduler on Windows), not tests inside the browser.
      Before you edit
      Read AGENTS.md. This Next.js has breaking changes, so read node_modules/next/dist/docs/ before writing app code. npm test is Vitest. Add a failing test before a behavior change. The Pages site has no dashboard button. Do not add one. Do not hand-edit generated plists or Task Scheduler jobs. install-agent is the source of truth.
      How to operate it
      npm run dev serves landing and dashboard on 0.0.0.0:3000. npm run speedtest runs one sample now. npm run install-agent creates Hourly if none exist, or rewrites every collector. npm run uninstall-agent unloads every Speedtape collector. Schedules are an interval (15 minutes through 24 hours) or clock times. This computer must be awake. If two jobs fire at once, the second waits. Override the database path with SPEEDTAPE_DB.
      Check Speedtest CLI
      This repo calls speedtest on Mac and speedtest.exe on Windows (lib/speedtest.ts). On Mac run command -v speedtest && speedtest --version. On Windows run where.exe speedtest. The version line should name Ookla. A missing binary, spawn ENOENT, or the stored error speedtest CLI was not found means it is not installed. The pip package speedtest-cli is the wrong tool. Install with the Mac or Windows commands on this page.
      Read logs without the dashboard
      Collectors write stdout to speedtape.out.log and stderr to speedtape.err.log. On Mac those files are in ~/Library/Logs/. On Windows they are in %APPDATA%\speedtape\. A successful run prints JSON with testedAt and speeds. A failed run prints Speed test failed: and the error. Missing files mean the collector has not run yet. Saved samples are also in SQLite table speed_tests. Query with SELECT tested_at, download_mbps, error FROM speed_tests ORDER BY id DESC LIMIT 20; against ~/Library/Application Support/speedtape/speedtests.db or %APPDATA%\speedtape\speedtests.db, or SPEEDTAPE_DB if it is set.