Runway — AI Subscription Limits Dashboard

Runway is a local-first monitoring tool that tracks remaining capacity and reset timers across your entire generative AI stack — aggregated into a single, clean dashboard with persistent history and fleet management.

Upgrading from the previous major version? See the v3 migration notes.

_{Dark theme shown. Light theme follows your OS preference or Settings → Display.}

Provider detail page — gauges, current-window forecast, per-model & per-window donuts, recent sessions (light)	Time range picker — Overview / Activity / Cost / Events / Sessions scope to a rolling window, a calendar month, or a custom span (token trend, composition, heatmap, sessions) (light)
History — % used / tokens / cost across windows with forecast overlay (light)	Settings — provider toggles, poll intervals, credentials, alerts, audit log, data health, version (light)
Fleet — sidecar registry with version, OS, ingest count, pause/resume, keep-alive, and untagged credentials to map (light)	Light theme — the dashboard following your OS preference or Settings → Display

• 15 Providers, 20+ Data Points: Monitor Claude, Gemini, GitHub Copilot, OpenRouter, MiniMax, Ollama, and more
• 3-Tier Fallback: APIs → Web scraping → Local files. If one fails, the next takes over
• Event-Sourced History: One immutable row per assistant message in usage_events — rollups, windows, and cost are all derived views over the same authoritative log
• Smart Caching: Configurable poll interval (default 15 min; per-provider or global override via Settings) plus a smart-sleep mode that stretches to ~2 hours after 45 min of no quota change
• Instant Serving: /limits returns from an in-memory registry — never blocks on collection
• Forecast Trajectories: Theil-Sen regression on quota snapshots projects exhaustion — surfaced on Fleet Commander gauges, the history chart overlay, and the per-provider detail page
• Persistent History: SQLite-backed usage snapshots with 15-minute background polling, hourly resolution on ≤7-day windows
• Provider Detail Page: A deep-linked per-provider view with Overview, Activity (token trend, composition, heatmap, sessions), Events (per-message stream), Forecast, and Cost tabs
• Unified Time Range: One time-range picker (quick ranges for the last 7/14/30/90 days, this/last month, plus a custom From/To span) shared by History, Insights, and every provider-detail tab — deep-linkable via ?range=Nd or ?range=YYYY-MM-DD_YYYY-MM-DD (legacy ?period= values still resolve), with all boundaries on your local timezone; Forecast stays fixed and the Home page keeps its own anchor
• Global Insights: A top-level /insights page with cross-provider lifetime totals, cache-hit ratio, busiest day/hour, and Top Models / Projects / Tools rankings
• Project & Tool Tracking: Events capture working directory, project, git branch, and tool names — surfaced as a Sessions project column, sortable session columns (duration / messages / tokens / cost), and the Insights rankings
• Provider Sections: Dashboard cards grouped by provider with context filter pills (Source / Account / Window)
• Fleet Management: Persistent registry of all sidecars with custom names, tags, version reporting, pause/resume controls, per-sidecar keep-alive toggle, activity tracking, and a banner for untagged credentials a sidecar found but you have not yet mapped to an account
• Credentials: Settings → Credentials shows where each account's credentials and data come from, with per-source provenance (which machine, env var, file or cookie), expiry status, and refresh or remove actions per source
• Keep-alive: Opt-in per sidecar (--keep-alive, or toggle it on Fleet) — the sidecar renews xAI (Grok) and Antigravity (agy) logins itself so they do not lapse while the CLI is idle (not supported by the tray app)
• Data Health: Settings → Data health runs read-only checks over the database (generic account IDs, legacy provider IDs, orphaned credential rows, rollup drift, unpriced models, and more) and offers an in-app fix — preview first, then apply
• Sidecar Ingestion: Push metrics and per-message events from external hosts via POST /api/v1/fleet/ingest (HMAC-signed, 600/min/IP rate limit)
• Webhook Alerts: Per-provider/per-account threshold alerts, plus credential alerts when a login expires or is rejected, to Discord or Slack
• Audit Log: Append-only record of admin mutations, viewable from the Settings panel
• Build Info: Settings → About reports the running server version alongside host, encryption, and auth status
• Session Auth: Admin login via an HttpOnly SameSite=Strict session cookie with "log out everywhere" revocation; scripts can still use the X-Admin-Key header
• Installable PWA: Add Runway to your home screen — app manifest, service worker, offline state banner, and a theme-color that follows the active theme
• Display Settings: Compact mode, 2-column layout, soft chrome — configurable per browser
• Resilient Rendering: Individual API failures show "Error Cards" instead of breaking the dashboard
• Docker Ready: Headless-first architecture for containerized environments with fail-fast multi-host startup gates (DB_ENCRYPTION_KEY, TLS_TERMINATED, CORS_ORIGINS, and ADMIN_API_KEY or TRUSTED_PROXY_IPS)

• Python 3.12+ and Node.js 18+ (for UI styling) are required.

# 1. Clone and setup (installs venv, dependencies, and git hooks)
git clone <repository-url> && cd runway
make install

# 2. Configure (add your API keys)
cp .env.example .env

# 3. Run the full dev stack — server + Vite frontend + local sidecar (Ctrl-C stops all)
make dev-all

Access the dev UI at http://localhost:5173 (Vite hot-reloads the frontend and proxies /api to the backend on :8765). Use make dev for the server only (no frontend, no cookie/local collectors), or make run-all to serve the production-built SPA from the backend at http://localhost:8765.

Runway includes a Makefile to automate common tasks. Run make help for the full list.

Use the shipped docker-compose.yml or the Traefik stack. Before starting, copy .env.example to .env and configure DB_ENCRYPTION_KEY, CORS_ORIGINS, and either ADMIN_API_KEY or a forward-auth proxy with TRUSTED_PROXY_IPS. Set TLS_TERMINATED=1 only when a proxy actually terminates TLS. The v3 migration guide explains why Docker now requires these settings; the Deployment Guide has the startup steps.

Run sidecar scripts on every host you want to monitor.

If you are running in Docker or a headless environment where browser scraping is impossible, you can manually provide authentication tokens in the Settings tab.

• API Key (Bearer Token): Paste the full token (usually starts with eyJ...). This takes higher priority than cookies.
• Session Cookie: Provide as a fallback if explicit tokens are not available.

Note: For ChatGPT and Claude, we recommend using the Bearer token in the "API Key" field for the most reliable connection.

Every GitHub release ships:

• Runway-Sidecar-macOS-<version>.dmg: drag-to-Applications installer for the menu-bar app (Apple Silicon)
• Runway-Sidecar-Windows-<version>-setup.exe: per-user installer for the tray app (no admin rights; Start Menu entry, uninstaller, optional start-at-sign-in)
• Runway-Sidecar-Linux-<version>.tar.gz: desktop tray app (needs AppIndicator/GTK + DBus)
• Runway-Sidecar-Linux-CLI-<version>.tar.gz: headless single-file binary for servers, Docker, and CI agents (no Python or GUI required)

It also ships portable .zip builds for macOS/Windows, which the in-app self-updater uses, plus SHA256SUMS.txt and Sigstore signatures for verification. The Fleet page of the dashboard links the right installer for your OS. Numbered beta prereleases are available from Fleet; the rolling edge prerelease is rebuilt when a push to main changes sidecar or installer files.

The desktop apps are not signed with an Apple Developer ID / Windows code-signing certificate, so the OS asks once before the first launch:

• macOS ("Apple could not verify this app…"): right-click Runway Sidecar in Applications → Open → Open. On macOS 15+, use System Settings → Privacy & Security → Open Anyway.
• Windows (SmartScreen: "Windows protected your PC"): click More info → Run anyway.

See docs/sidecar.md for install, uninstall, silent-install and verification details.

15 providers with server-side quota collectors. A sidecar supplies host-local credentials and per-message events where needed.

For Antigravity on a remote host, the sidecar sends the agy OAuth token to the server for quota collection and extracts local conversation events. On the same host, the server can read the token file directly.

Env Var Legend: (opt) = Optional, has fallback | — = Detected automatically

Runway is always server + sidecar(s). Two orthogonal axes vary: the server can run as Python (make dev-all / make run) or in Docker, and you can run one sidecar locally or N sidecars across remote hosts. All cookie, IDE, and local-file detection lives in the sidecar; the server handles API/web collection, aggregation, and the dashboard.

👉 Full Deployment Guide with the per-provider compatibility matrix and Docker Compose examples

All routes are mounted under /api/v1/. See docs/api-reference.md for the full route inventory (usage, fleet/ingestion, system, auth) and the LimitCard response payload schema.

RUNWAY_CONFIG_DIR — Override the default platform-specific configuration directory. This controls where Runway stores its database (runway.db), external metrics, and OAuth tokens. This is especially useful for Docker deployments or when you need to store configuration in a non-default location.

ADMIN_API_KEY — When set, the dashboard and admin API endpoints are protected. Unset by default (local-first, single-user). Remote access triggers a Login Screen.

DB_ENCRYPTION_KEY — Fernet key for encrypting sensitive metadata in SQLite. Unset = plaintext (acceptable for local deployments). Back up this key alongside the database file.

TLS_TERMINATED — Operator assertion that TLS is terminated upstream (nginx, caddy, cloudflare, kube ingress). Required when APP_HOST is not localhost — sidecar payloads carry tokens, and HMAC protects integrity but not confidentiality. See Multi-Host Startup Gates.

CORS_ORIGINS — Comma-separated allow-list of origins for cross-origin requests. Required when APP_HOST is not localhost.

TRUSTED_PROXY_IPS — Comma-separated list of reverse-proxy source IPs allowed to assert identity via a forward-auth header (X-Forwarded-User by default; FORWARD_AUTH_USER_HEADER and friends make the header names configurable, e.g. for Authentik). Without an IP allow-list these headers are forgeable and bypass ADMIN_API_KEY. See the Forward-Auth / SSO guide.

LOG_FORMAT — plain (default) or json for structured logging.

TZ — IANA timezone for dashboard display (e.g. Europe/Berlin). Browser auto-detect is used when unset; the Settings panel can override per user.

By default, Runway binds to 127.0.0.1 (local only). To access from other devices on your network:

1. Set APP_HOST=0.0.0.0 in .env
2. Restart Runway
3. Access via http://<your-ip>:8765

Runway provides a flexible, multi-layered security model:

• Local Trust: When accessing Runway from 127.0.0.1 (localhost), authentication is automated. You will jump straight to the dashboard even if an ADMIN_API_KEY is set.
• Login Screen: For remote access or Docker deployments, setting ADMIN_API_KEY in your .env triggers a dedicated Login Portal. Enter the key once, and it's exchanged for an HttpOnly session cookie — never stored in localStorage.
• Forward-Auth / SSO (Proxy): If you offload authentication to a reverse proxy (Authentik, Authelia, oauth2-proxy, Cloudflare Access, …), Runway automatically trusts and bypasses the login screen once TRUSTED_PROXY_IPS is set — configurable header names and an optional group/user allow-list mean the admin key never needs to be entered in the browser at all. See the Forward-Auth / SSO guide for a full Authentik + Traefik walkthrough, including production hardening (bypassing SSO for sidecar ingestion and static assets) and troubleshooting.

⚠️ Public Internet: Never expose Runway directly to the public internet without a reverse proxy (Nginx/Traefik) and HTTPS.

AGPL-3.0 License - see LICENSE file.

Last updated: 2026-06-14