Reference
CLI & Environment Reference Complete table of every CLI flag and environment variable that TokenTelemetry recognizes.
This is the authoritative reference for the TokenTelemetry launcher CLI and every environment variable the launcher and backend recognize. Run it with ./start.sh (or node bin/cli.js) from inside the cloned tokentelemetry/ folder — there is no global tokentelemetry command.
# from inside the tokentelemetry/ folder: ./start.sh [options] # macOS / Linux node bin/cli.js [options] # cross-platform Flag Short Default Description --port <N>-p3000Frontend (Next.js) port --api-port <N>-a8000Backend (FastAPI) port --data-dir <path>-d~/.tokentelemetryWhere TokenTelemetry stores config and state. Sets TOKENTELEMETRY_DATA_DIR. --host <addr>127.0.0.1Backend bind address. Use 0.0.0.0 (or a specific IP) to expose remotely. --allowed-origins <list>(empty) Comma-separated hosts allowed to load the dashboard from another machine (CORS + Next.js dev origins). --auth-token <token>(auto-generated) Access token required for remote requests. If --host is non-loopback and this is omitted, a random token is generated and printed once. --insecure-no-authfalseDisable the remote access token entirely. Only safe on a fully trusted private network. --help-hPrint help and exit.
# Default: frontend on 3000, backend on 8000, localhost only ./start.sh # Custom ports ./start.sh --port 4000 --api-port 9000 # Frontend on 4000, backend stays 8000 ./start.sh -p 4000 # Expose on a tailnet/LAN with auto-generated token ./start.sh --host 0.0.0.0 \ --allowed-origins box.tailnet.ts.net,100.64.0.1 # Expose with a fixed token ./start.sh --host 0.0.0.0 --auth-token my-secret # Store config and state on a secondary drive ./start.sh --data-dir /mnt/d/tt-data Variable Description TOKENTELEMETRY_DATA_DIRSets the data directory (used verbatim, no .tokentelemetry suffix). --data-dir flag wins. TT_AUTH_TOKENAccess token for remote requests. --auth-token flag wins. AGENT_HARNESS_NO_OPENSet to any non-empty value to skip auto-opening the browser on startup. NEXT_PUBLIC_API_PORTPassed to the Next.js dev server to tell the frontend which port the backend is on. Set automatically by the launcher from --api-port. NEXT_PUBLIC_API_BASEFull backend URL override (e.g. http://localhost:8000). Overrides the runtime auto-detection from window.location. Useful in SSH-tunnel setups.
Variable Description TOKENTELEMETRY_DATA_DIRData directory, used verbatim. Highest precedence. TOKENTELEMETRY_HOMEOverride of the home directory; .tokentelemetry is appended as a subfolder. Lower precedence than TOKENTELEMETRY_DATA_DIR. TT_AUTH_TOKENAccess token for the remote-auth gate. Empty string = no token required (set by the launcher when --insecure-no-auth is used). TT_ALLOWED_ORIGINSComma-separated CORS allowlist. Set by the launcher from --allowed-origins. TT_REMOTE_CONNECT_URLFull URL (with token) printed for the QR code. Set by the launcher. TT_NO_UPDATE_CHECKSet to 1 to disable the hourly update check entirely. Wins over the in-app toggle. TT_NO_TELEMETRYSet to 1 to disable anonymous product telemetry. Wins over the in-app toggle. DO_NOT_TRACKSet to 1 to disable product telemetry (same effect as TT_NO_TELEMETRY). TT_PROJECT_ROOTSComma-separated list of additional directories to scan for agent sessions (beyond the default ~/.claude/, ~/.codex/, etc.). TT_API_PORTBackend port, as an alternative to --api-port. TT_HOSTBackend bind address, as an alternative to --host. HERMES_HOMEPath to the Hermes Agent data directory. Default: ~/.hermes/.
Variable Backend Description TT_OLLAMA_TIMEOUTOllama Request timeout in seconds. Default: 360. TT_CODEX_TIMEOUTCodex Request timeout in seconds. Default: 300. TT_OPENAI_COMPAT_TIMEOUTOpenAI-compatible Request timeout in seconds. Default: 120. OPENAI_COMPAT_API_KEYOpenAI-compatible Bearer token for the OpenAI-compatible endpoint. Wins over the value stored in summarizer.json. OPENAI_COMPAT_USER_AGENTOpenAI-compatible HTTP User-Agent header. Default: TokenTelemetry/1.0 (+https://github.com/VasiHemanth/tokentelemetry).