TTDash is a local-first dashboard and CLI for
toktrack usage data. Explore costs, tokens, requests,
models, providers, forecasts, and exports without sending your usage data to a hosted TTDash
backend.
Run the latest release without a global installation:
npx --yes @roastcodes/ttdash@latestOr use Bun:
bunx @roastcodes/ttdash@latestTTDash starts on http://127.0.0.1:3000, selects a nearby free port when necessary, and
opens your browser. You can then auto-import current toktrack data, upload supported JSON, or
restore a TTDash usage backup.
For a global installation:
npm install --global @roastcodes/ttdash
ttdash- Cost, token, request, cache, model, provider, weekday, and calendar analysis
- Daily, monthly, yearly, preset, and custom date filters
- Forecasts, comparisons, anomalies, cache ROI, limits, and concentration insights
toktrackand legacy daily JSON imports plus TTDash backup restore- CSV export and localized PDF reports when Typst is installed
- Local-first storage, configurable dashboards, themes, keyboard navigation, and Docker support
TTDash builds on the data produced by toktrack. Thanks to
mag123c for creating and maintaining it.
The documentation site is the source of truth for installation, usage, deployment, and contributor guidance:
| Topic | Guide |
|---|---|
| Install and first run | Getting started |
| Import usage data | Importing data |
| Use dashboards and filters | Dashboard guide |
| Configure the CLI and storage | Configuration reference |
| Deploy securely | Remote access and Docker |
| Integrate with the server | HTTP API |
| Work on TTDash | Architecture and testing |
Start at roastcodes.github.io/ttdash. Every page has
an edit link, and the site is built and checked from the versioned source in
docs-site/src/content/docs.
- Node.js 20 or newer for npm/npx installations
- A modern browser
- npm or Bun when TTDash needs to run
toktrackfor auto-import - Typst only for PDF export
- Docker with Compose v2 only for container deployments
TTDash binds to loopback by default. For a non-loopback bind, deliberately enable remote access and provide a token of at least 24 characters:
export TTDASH_REMOTE_TOKEN="$(openssl rand -hex 32)"
TTDASH_ALLOW_REMOTE=1 HOST=0.0.0.0 ttdashAPI clients can use either supported authentication header:
curl -H "Authorization: Bearer $TTDASH_REMOTE_TOKEN" http://192.0.2.10:3000/api/usage
curl -H "X-TTDash-Remote-Token: $TTDASH_REMOTE_TOKEN" http://192.0.2.10:3000/api/usageUse remote HTTP only on a trusted LAN, VPN, or SSH tunnel. Public hostnames require an HTTPS reverse proxy; do not send the token or session over public HTTP. Read the remote-access guide and security policy before exposing TTDash beyond loopback.
Building and testing the repository requires Node.js 22.13 or newer on an even-numbered release; the published TTDash CLI continues to support Node.js 20 and newer. CI uses Node.js 24 for the development toolchain.
Install dependencies and run the Vite frontend:
npm install
npm run devRun node server.js in a second terminal for the local API. Before opening a pull request, run:
npm run verify:full
npm run docs:install
npm run docs:verify
npm run test:docs:e2eSee CONTRIBUTING.md for the full workflow.
TTDash is available under the MIT License.