TokenTelemetry

https://tokentelemetry.com/docs
Admin
TokenTelemetry is a free, local-first observability dashboard for AI coding agents that tracks token...
Tokens:14,577
Snippets:264
Trust Score:4.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start TokenTelemetry

Source: https://tokentelemetry.com/docs/quick-start

Commands to launch the application from the installation directory.

```bash
cd tokentelemetry
./start.sh            # macOS / Linux
# start.bat           # Windows
# node bin/cli.js     # cross-platform
```

--------------------------------

### Quick Start TokenTelemetry with Hermes

Source: https://tokentelemetry.com/docs/features/hermes

Commands to install the plugin, start the TokenTelemetry service, and access the Hermes surface.

```bash
# Install the Hermes Dashboard plugin (optional but recommended)
hermes plugins install VasiHemanth/tokentelemetry-hermes-plugin

# Start TokenTelemetry on the same host as Hermes (from inside the cloned folder)
cd tokentelemetry && ./start.sh

# Open the Hermes surface
open http://localhost:3000/hermes
```

--------------------------------

### Start Ollama server

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Command to initialize the Ollama backend server.

```bash
ollama serve
```

--------------------------------

### Start TokenTelemetry manually

Source: https://tokentelemetry.com/docs/installation

Launch the application from within the installation directory.

```bash
cd tokentelemetry
./start.sh          # macOS / Linux   (or: node bin/cli.js)
```

--------------------------------

### Configure TokenTelemetry with CLI Flags

Source: https://tokentelemetry.com/docs/reference/cli

Examples of starting the application with custom ports, host binding, and data directory paths.

```bash
# 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
```

--------------------------------

### Install and initialize Podman on macOS

Source: https://tokentelemetry.com/docs/docker

Commands to install Podman and initialize the required Linux VM for container execution.

```bash
brew install podman podman-compose
podman machine init --now
```

--------------------------------

### Run Agent Sessions

Source: https://tokentelemetry.com/docs/quick-start

Examples of starting common AI agent sessions that TokenTelemetry will automatically detect.

```bash
# Example: Claude Code
claude

# Example: Gemini CLI
gemini

# Example: OpenAI Codex
codex
```

--------------------------------

### Install Hermes Dashboard Plugin

Source: https://tokentelemetry.com/docs/features/hermes

Installs the TokenTelemetry plugin for the Hermes web UI.

```bash
hermes plugins install VasiHemanth/tokentelemetry-hermes-plugin
hermes dashboard
```

--------------------------------

### Launch TokenTelemetry via CLI

Source: https://tokentelemetry.com/docs/reference/cli

Commands to start the application from within the project directory.

```bash
# from inside the tokentelemetry/ folder:
./start.sh [options]          # macOS / Linux
node bin/cli.js [options]     # cross-platform
```

--------------------------------

### Initialize and start TokenTelemetry containers

Source: https://tokentelemetry.com/docs/docker

Clone the repository and launch the services using the Makefile. Ensure environment variables like TZ and ports are configured before the first run to avoid rebuilds.

```bash
git clone https://github.com/VasiHemanth/tokentelemetry.git
cd tokentelemetry
TZ=Asia/Kolkata PORT=13000 TT_API_PORT=18000 make up
```

--------------------------------

### Install via one-line command

Source: https://tokentelemetry.com/docs/installation

Use these commands to clone and launch TokenTelemetry automatically on your system.

```bash
curl -fsSL https://tokentelemetry.com/install.sh | bash
```

```powershell
irm https://tokentelemetry.com/install.ps1 | iex
```

--------------------------------

### Start with custom ports

Source: https://tokentelemetry.com/docs/installation

Override default ports if they are already in use by another process.

```bash
./start.sh --port 3100 --api-port 8100
```

--------------------------------

### Run production images with make

Source: https://tokentelemetry.com/docs/docker

Use these commands to pull and start the production containers, optionally pinning a specific image tag.

```bash
make up-prod                          # pull the latest images and start detached
TT_IMAGE_TAG=sha-abc1234 make up-prod # pin a specific build instead of latest
```

--------------------------------

### Update TokenTelemetry

Source: https://tokentelemetry.com/docs/installation

Update the local installation by pulling the latest changes from the repository.

```bash
cd tokentelemetry   # the folder you installed into
git pull
./start.sh          # start.bat on Windows
```

--------------------------------

### Verify Python Version

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Check that the installed Python version meets the minimum requirement of 3.9+.

```bash
python3 --version   # should show 3.9+
```

--------------------------------

### Configure Agent Log Mounts in compose.yml

Source: https://tokentelemetry.com/docs/docker

Uncomment the specific agent paths required for your setup. The :ro flag ensures read-only access, while :z handles SELinux relabeling.

```yaml
volumes:
  - tt_data:/tt-data
  - "${HOME}/.claude:/root/.claude:ro,z"
  # - "${HOME}/.codex:/root/.codex:ro,z"
  # - "${HOME}/.gemini:/root/.gemini:ro,z"
  # - "${HOME}/.cline:/root/.cline:ro,z"
  # - "${HOME}/.copilot:/root/.copilot:ro,z"
  # - "${HOME}/.cursor:/root/.cursor:ro,z"
  # - "${HOME}/.grok:/root/.grok:ro,z"
  # - "${HOME}/.hermes:/root/.hermes:ro,z"
  # - "${HOME}/.pi:/root/.pi:ro,z"
  # - "${HOME}/.qwen:/root/.qwen:ro,z"
  # - "${HOME}/.vibe:/root/.vibe:ro,z"
  # - "${HOME}/.local/share/opencode:/root/.local/share/opencode:ro,z"
  # macOS VS Code / Cursor extension storage (paths contain spaces — keep them quoted):
  # - "${HOME}/Library/Application Support/Code/User:/root/.config/Code/User:ro,z"
  # - "${HOME}/Library/Application Support/Cursor/User:/root/.config/Cursor/User:ro,z"
```

--------------------------------

### Remote Access Token Output

Source: https://tokentelemetry.com/docs/configuration/remote-access

Example of the terminal output generated when remote access is enabled.

```text
──────────────────────────────────────────────────────────
Remote access is ON. Other devices must enter this token:

    abc123xyz...

Or skip the typing — open this link (or scan its QR from the
dashboard's "Connect a device" panel) on the other device:

    http://192.168.1.10:3000/?token=abc123xyz...

The token is shown once — re-run to rotate it.
──────────────────────────────────────────────────────────
```

--------------------------------

### Uninstall TokenTelemetry

Source: https://tokentelemetry.com/docs/installation

Remove the application by deleting the installation folder and the local data directory.

```bash
# from the directory where you installed it:
rm -rf tokentelemetry ~/.tokentelemetry
```

--------------------------------

### Disable Authentication

Source: https://tokentelemetry.com/docs/configuration/remote-access

Starts the service without token authentication, binding to all interfaces. Use only on trusted private networks.

```bash
./start.sh --host 0.0.0.0 --insecure-no-auth
```

--------------------------------

### Pin backend URL with NEXT_PUBLIC_API_BASE

Source: https://tokentelemetry.com/docs/configuration/ports-networking

Use this variable to explicitly define the backend URL, overriding automatic discovery for complex network setups like SSH tunnels.

```bash
NEXT_PUBLIC_API_BASE=http://localhost:8000 ./start.sh
```

--------------------------------

### Configure Allowed Origins for CORS

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Specify allowed hostnames when starting the service to prevent CORS errors in the browser.

```bash
./start.sh --host 0.0.0.0 --allowed-origins 192.168.1.42,box.tailnet.ts.net
```

--------------------------------

### Clone and run from source

Source: https://tokentelemetry.com/docs/installation

Manually clone the repository to inspect the source or pin to a specific version.

```bash
git clone https://github.com/VasiHemanth/tokentelemetry.git
cd tokentelemetry
./start.sh        # macOS / Linux
```

```batch
start.bat         # Windows
```

```javascript
node bin/cli.js
```

--------------------------------

### Configure service ports via CLI

Source: https://tokentelemetry.com/docs/configuration/ports-networking

Use the --port and --api-port flags to override default service ports during startup.

```bash
# Custom frontend port only (backend stays 8000):
./start.sh --port 4000
./start.sh -p 4000

# Custom backend port only (frontend stays 3000):
./start.sh --api-port 9000
./start.sh -a 9000

# Both:
./start.sh --port 4000 --api-port 9000
```

--------------------------------

### Run Multiple Instances

Source: https://tokentelemetry.com/docs/configuration/data-directory

Run independent instances by assigning unique data directories and ports to each process.

```bash
# Instance A
./start.sh --data-dir ~/tt-work --port 3000 --api-port 8000

# Instance B
./start.sh --data-dir ~/tt-personal --port 3001 --api-port 8001
```

--------------------------------

### Configure TokenTelemetry ports

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Override default ports during startup using command-line arguments.

```bash
./start.sh --port 4000 --api-port 9000
```

--------------------------------

### Configure WSL Mount Paths

Source: https://tokentelemetry.com/docs/docker

Adjust mount sources to point to the Windows filesystem when running agents from WSL.

```yaml
- "/mnt/c/Users/<you>/.claude:/root/.claude:ro,z"
```

--------------------------------

### Set Data Directory via Environment Variables

Source: https://tokentelemetry.com/docs/configuration/data-directory

Use TOKENTELEMETRY_DATA_DIR for an exact path or TOKENTELEMETRY_HOME to append a .tokentelemetry subdirectory.

```bash
# Exact path (no suffix appended):
export TOKENTELEMETRY_DATA_DIR=/mnt/d/tt-data
./start.sh

# Home override (appends .tokentelemetry):
export TOKENTELEMETRY_HOME=/mnt/d
# → data dir: /mnt/d/.tokentelemetry
./start.sh
```

--------------------------------

### Configure summarizer timeouts

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Environment variables to increase timeout thresholds for different backends.

```bash
TT_OLLAMA_TIMEOUT=600
```

```bash
TT_CODEX_TIMEOUT=600
```

```bash
TT_OPENAI_COMPAT_TIMEOUT=300
```

--------------------------------

### Supply a Fixed Authentication Token

Source: https://tokentelemetry.com/docs/configuration/remote-access

Use a static token to avoid rotation on restart, provided via command-line flag or environment variable.

```bash
./start.sh --host 0.0.0.0 --auth-token mysecrettoken
```

```bash
TT_AUTH_TOKEN=mysecrettoken ./start.sh --host 0.0.0.0
```

--------------------------------

### Authenticate backend CLI

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Commands to authenticate various AI model providers via CLI or environment variables.

```bash
claude login
export ANTHROPIC_API_KEY=sk-...
```

```bash
codex login
export OPENAI_API_KEY=sk-...
```

```bash
gemini auth
export GEMINI_API_KEY=...
```

```bash
qwen auth
export DASHSCOPE_API_KEY=...
```

--------------------------------

### Set authentication token for Docker containers

Source: https://tokentelemetry.com/docs/docker

Pass an authentication token to the backend container via environment variables during startup.

```bash
TT_AUTH_TOKEN=your-secret-token make up
```

--------------------------------

### Migrate Existing Data Directory

Source: https://tokentelemetry.com/docs/configuration/data-directory

Move the existing directory to a new location and point the application to it using the --data-dir flag.

```bash
mv ~/.tokentelemetry /mnt/d/tt-data
./start.sh --data-dir /mnt/d/tt-data
```

--------------------------------

### Set a Predictable Auth Token

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Use a static authentication token to avoid manual entry or QR code scanning.

```bash
./start.sh --host 0.0.0.0 --auth-token my-stable-token
```

--------------------------------

### Set Data Directory via Flag

Source: https://tokentelemetry.com/docs/configuration/data-directory

Use the --data-dir or -d flag to specify a custom path. The directory is created automatically upon the first write.

```bash
./start.sh --data-dir /mnt/d/tt-data
# or shorthand:
./start.sh -d /mnt/d/tt-data
```

--------------------------------

### Configure Direct Remote Access

Source: https://tokentelemetry.com/docs/configuration/remote-access

Expose the dashboard to external networks by binding to all interfaces and specifying allowed origins.

```bash
./start.sh \
  --host 0.0.0.0 \
  --allowed-origins your-laptop.tailnet.ts.net,192.168.1.42 \
  --port 3000 \
  --api-port 8000
```

--------------------------------

### Verify agent log directory existence

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Check that the expected log directory for your specific agent contains session files.

```bash
ls ~/.claude/projects/
```

--------------------------------

### Establish SSH Tunnel

Source: https://tokentelemetry.com/docs/configuration/remote-access

Forwards both the dashboard and API ports from the remote host to the local machine.

```bash
ssh -N -L 3000:127.0.0.1:3000 -L 8000:127.0.0.1:8000 user@remote-host
```

--------------------------------

### Override host ports

Source: https://tokentelemetry.com/docs/docker

Use environment variables to map custom host ports to the application containers.

```bash
PORT=3200 TT_API_PORT=8200 make up
```

--------------------------------

### Restart Podman machine

Source: https://tokentelemetry.com/docs/docker

Clear stale port-forward entries on macOS by restarting the Podman machine.

```bash
make machine-restart
```

--------------------------------

### Suppress Browser Auto-Open

Source: https://tokentelemetry.com/docs/quick-start

Environment variable configuration to prevent the browser from opening in headless environments.

```bash
AGENT_HARNESS_NO_OPEN=1 ./start.sh    # or: AGENT_HARNESS_NO_OPEN=1 node bin/cli.js
```

--------------------------------

### Configure SSH Tunnel for Remote Access

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Set the API base URL on the remote machine and forward both frontend and backend ports via SSH to resolve blank dashboard issues.

```bash
# On the remote machine:
NEXT_PUBLIC_API_BASE=http://localhost:8000 ./start.sh

# On your laptop:
ssh -N -L 3000:127.0.0.1:3000 -L 8000:127.0.0.1:8000 user@remote-host
```

--------------------------------

### Configure Specific Host Access

Source: https://tokentelemetry.com/docs/configuration/remote-access

Binding to a specific IP automatically adds it to the CORS allowlist.

```bash
# --host 192.168.1.10 automatically adds 192.168.1.10 to the CORS allowlist:
./start.sh --host 192.168.1.10
```

--------------------------------

### Energy and Cost Calculation Formulas

Source: https://tokentelemetry.com/docs/configuration/local-models

Mathematical formulas used by TokenTelemetry to derive energy consumption, financial cost, and carbon emissions from session duration and hardware power draw.

```text
energy (Wh) = wattage (W) × session_duration (hours)
cost ($)    = energy (kWh) × electricity_rate ($/kWh)
CO₂ (g)     = energy (kWh) × grid_carbon_intensity (gCO₂/kWh)
```

--------------------------------

### Insecure Auth Warning

Source: https://tokentelemetry.com/docs/configuration/remote-access

The warning message displayed by the launcher when authentication is disabled.

```text
⚠  WARNING: --insecure-no-auth — the dashboard is exposed to the
   network with NO access token. Anyone who can reach this host can
   read your data and change settings. Only use this on a fully
   trusted private network (e.g. a tailnet).
```

--------------------------------

### Override Backend Timeout via Environment Variable

Source: https://tokentelemetry.com/docs/configuration/configure-summarizer

Set the timeout duration for a specific backend before launching the application to handle long traces or slow models.

```bash
TT_OLLAMA_TIMEOUT=600 tokentelemetry
```

--------------------------------

### Override API port for development

Source: https://tokentelemetry.com/docs/configuration/ports-networking

Manually set the NEXT_PUBLIC_API_PORT environment variable when running the frontend independently.

```bash
NEXT_PUBLIC_API_PORT=9000 npm run dev
```

--------------------------------

### Workflow Directory Structure

Source: https://tokentelemetry.com/docs/features/automation

The file path pattern used by the Workflow tool to store agent data, which necessitates a dedicated scan pass.

```text
<session>/subagents/workflows/wf_<id>/agent-<agentId>.jsonl
<session>/subagents/workflows/wf_<id>/journal.jsonl
```

--------------------------------

### Disable Product Telemetry via Environment Variable

Source: https://tokentelemetry.com/docs/configuration/privacy

Use the TT_NO_TELEMETRY environment variable to disable anonymous product telemetry.

```bash
TT_NO_TELEMETRY=1 tokentelemetry
```

--------------------------------

### Override billing modes in billing.json

Source: https://tokentelemetry.com/docs/configuration/billing

Manually define billing modes for specific agents by editing the configuration file located at ~/.tokentelemetry/billing.json.

```json
{
  "cursor": "subscription",
  "opencode": "api",
  "vibe": "local"
}
```

--------------------------------

### Identify processes occupying ports

Source: https://tokentelemetry.com/docs/configuration/ports-networking

Commands to find the process ID (PID) currently using a specific port on different operating systems.

```bash
ERROR: required port(s) already in use: 3000
Stop whatever is listening on those ports and try again.
Tip: `lsof -iTCP:3000 -sTCP:LISTEN` shows the culprit.
```

```bash
Tip: `netstat -ano | findstr :3000` shows the culprit PID.
```

--------------------------------

### Identify and terminate processes using specific ports

Source: https://tokentelemetry.com/docs/reference/troubleshooting

Commands to find and stop processes occupying ports 3000 or 8000 on various operating systems.

```bash
# macOS / Linux:
lsof -iTCP:3000 -sTCP:LISTEN
kill <PID>

# Windows:
netstat -ano | findstr :3000
taskkill /PID <PID> /F
```

--------------------------------

### Release occupied ports

Source: https://tokentelemetry.com/docs/configuration/ports-networking

Commands to list and terminate processes blocking a port on macOS or Linux.

```bash
# macOS / Linux — find the process:
lsof -iTCP:3000 -sTCP:LISTEN

# Kill it:
kill <PID>
```

--------------------------------

### Access Dashboard

Source: https://tokentelemetry.com/docs/quick-start

The local URL for the TokenTelemetry dashboard.

```text
http://localhost:3000
```

--------------------------------

### Set container timezone

Source: https://tokentelemetry.com/docs/docker

Explicitly define the timezone for the container to ensure correct time-based data processing.

```bash
TZ=Asia/Kolkata make up
```

--------------------------------

### Override Docker Compose ports for remote access

Source: https://tokentelemetry.com/docs/docker

Use this override file to expose ports to the network instead of the default loopback interface.

```yaml
# compose.override.yml
services:
  backend:
    ports: ["0.0.0.0:${TT_API_PORT:-18000}:8000"]
  frontend:
    ports: ["0.0.0.0:${PORT:-13000}:3000"]
```

--------------------------------

### Disable Update Check via Environment Variable

Source: https://tokentelemetry.com/docs/configuration/privacy

Use the TT_NO_UPDATE_CHECK environment variable to disable the automatic update check feature.

```bash
TT_NO_UPDATE_CHECK=1 tokentelemetry
```

```bash
export TT_NO_UPDATE_CHECK=1
```
Tokens:
Raw