Install TokenTracker with npm: Localtonet Remote Access

Understand the local dashboard and remote-access boundary

TokenTracker runs where your supported AI coding tools keep their usage information. Its project website documents a one-command npm launch, automatic detection of installed tools, and a browser dashboard at http://localhost:7680. Depending on the integration, collection uses a session-end hook, a notification configuration, a plugin, or a passive reader.

The dashboard presents usage totals, estimated costs, trends, model information, project attribution, and related views. Token categories can include input, output, cached, and cache-creation tokens when the underlying source provides them. Coverage changes over time, so this guide does not fix a tool count or imply that every source supplies identical metrics.

TokenTracker describes its privacy model as “token counts only,” not prompts or conversations, with account-free local use and optional cloud synchronization. These are project-attributed statements, not a guarantee from Localtonet about every reader, feature, or outbound request. For example, a provider-status view and local usage collection have different functions. Review the features you enable rather than assuming “local-first” means that every feature is offline.

With Localtonet, our client establishes an outbound connection to a relay server and forwards requests to a reachable local target. An HTTP tunnel supplies a public HTTPS address without inbound router port forwarding or a public IP address. Standard HTTP tunneling is not a VPN, and a public address does not authenticate visitors.

Check npm compatibility before executing the package

Use the operating-system account that normally runs your AI coding tools. That account should be able to read the relevant local data and review any configuration changes. Avoid an administrator account or service identity simply to work around permission errors: a different home directory can produce a working dashboard with no expected usage.

In the terminal you intend to use, check your tooling:

node --version
npm --version
npx --version

If these commands are unavailable, install Node.js and its npm tooling through your normal trusted operating-system or Node.js installation method. Reopen the terminal afterward. Prefer a currently maintained Node.js release that satisfies the package’s runtime declaration. A package’s minimum compatible version and an actively maintained Node.js release are different things.

Read the published package metadata

The project’s documented launch command establishes the package name, but does not by itself establish an exact Node.js minimum, a global executable name, or a complete npm platform-support matrix. Query those properties rather than treating a previous tutorial’s Node.js 20+ claim as verified:

npm view tokentracker-cli@latest version engines bin os cpu repository homepage --json
npm view tokentracker-cli@latest readme

These commands retrieve registry metadata without installing or running TokenTracker. Check that the repository and homepage correspond to the TokenTracker project. Record the returned version so that you can associate later behavior with a particular release.

The project also publishes native desktop releases, including Windows, macOS, and Linux assets. Those assets do not establish that the npm package or every integration behaves identically on each platform. This article stays with npm and does not combine native installers with the CLI workflow.

Before launching, back up configuration files for tools you expect TokenTracker to integrate with. Keep those backups private because they may contain unrelated credentials or settings. Ensure port 7680 is available, and do not disable host security controls to resolve a startup failure.

Launch TokenTracker with npm

The shortest documented installation and launch path is:

npx tokentracker-cli

Review any npm installation prompt before accepting it. On first run, npm may need to retrieve the package. TokenTracker then detects supported installed coding tools, configures the applicable integrations, and starts the local dashboard according to the project’s published workflow.

Keep startup output visible until you have completed the checks below. Look for the dashboard address, detected integrations, configuration changes, and any errors. Do not infer from the command returning that the server has stopped, or from an occupied terminal that every component runs in that foreground process. The exact foreground, detached-process, and shutdown behavior must be checked for the installed release.

Optional global installation

npm can install the package globally:

npm install --global tokentracker-cli

Use this route only if you want a global installation and have checked the package’s bin mapping. If that mapping exports tokentracker, that is the corresponding command to launch; otherwise use the actual exported name. This guide does not assume the executable mapping without the metadata check.

A global install and an npx launch are alternatives, not two required phases. Avoid starting multiple instances while testing. If a global executable is unavailable after installation, inspect npm’s global prefix and your shell path:

npm prefix --global
npm list --global tokentracker-cli --depth=0

Opening a new terminal may resolve a stale environment. Reinstalling repeatedly with elevated privileges is not a sound path fix.

Verify the dashboard and its data locally

Open the dashboard on the host

Use a browser on the computer running TokenTracker:

http://localhost:7680

localhost refers to the machine running the browser. Entering that URL on a phone will not connect to your development computer. If the page fails, inspect startup output before investigating tunnels.

Also test the explicit IPv4 loopback address:

http://127.0.0.1:7680

127.0.0.1 is a concrete same-device target, but its success must be checked: localhost may resolve to IPv6 on some systems. If the hostname works and IPv4 does not, do not assume the application listens on both address families.

Check more than the initial HTML

Open your browser’s developer tools, select the Network panel, and reload. Inspect the requests used to populate the usage views, including Fetch/XHR requests and any other live connections the application actually makes. No TokenTracker API path is assumed here: use the real requests from your installed version.

• Confirm that the dashboard’s data requests complete rather than failing while a static page remains visible.
• Check that responses contain the expected data format, not an HTML error page.
• Change a date range or open another usage view and confirm that it updates.
• Inspect the browser console for connection, parsing, or origin errors.
• Record a local baseline without copying private response bodies into public reports.

A successful HTTP response is not enough if the application displays stale or empty information. Conversely, an empty dataset with successful requests may be a collection problem rather than a web-server failure.

Understand and verify integration changes

Automatic setup can change coding-tool configuration. The project identifies Claude Code’s SessionEnd hook, Codex’s TOML notification array, and several passive local readers as collection mechanisms. The following reference explains what to inspect without inventing hook payloads or overwriting your existing settings.

The ~ notation refers to the user’s home directory. A passive reader does not require you to invent a notification command. Do not edit a tool’s database or usage logs to manufacture a successful test.

For hook-based integrations, compare configuration against your backup. Existing hooks and notification handlers matter: do not replace unrelated settings with an empty example or assume automatic setup preserved every customization. The precise inserted command and configuration schema are version-specific, so use the generated change and the matching project instructions as the authority.

For each integration you care about, note a baseline total and time range, perform a small normal session, and refresh the appropriate view afterward. Allow for the source’s collection timing. Check the source label, model, and project attribution where available. Estimated costs are not necessarily a provider invoice reconciliation, and cached or deduplicated activity can make a simple “one action equals one visible row” expectation misleading.

If nothing changes, check the operating-system user, detected tool, configuration diff, and source availability before reinstalling. An integration-specific failure does not imply that every other reader is broken.

Operate, update, and remove the npm installation carefully

The project documentation and version 1.5.0 release notes provide project and release context; the latter is a particular release, not a claim about the current npm version. Keep a record of the package version, launch method, and integration changes on your machine.

Stop and restart without assuming a daemon model

A universal TokenTracker stop or restart command is not established here. If the application demonstrably runs in the foreground, use the terminal’s normal interrupt, usually Ctrl+C, then verify whether the endpoint has stopped responding. If the CLI detached a server, closing the terminal is not proof of shutdown.

Use your operating system’s process and listening-port tools to identify the process serving port 7680. Confirm its identity before stopping anything. Do not use a broad command that terminates every Node.js process. Prefer the installed release’s documented graceful shutdown method when one is provided.

Before restarting, confirm that an old instance is not still listening. Launch using the same installation route and user context, then repeat the local page, API, and collection checks. The dashboard server and collection integrations may have different lifecycles; a stopped web page does not prove that hooks have been removed.

Update through npm

For a global installation, the standard npm command to install the version tagged latest is:

npm install --global tokentracker-cli@latest

For an explicit latest-tag npx launch:

npx tokentracker-cli@latest

These are npm package operations, not TokenTracker migration or restart commands. Review release notes and back up integration settings before updating. Installing a new package does not prove that an already-running process has loaded the new code. Stop the existing instance safely, update, relaunch, and check collection again. An unqualified npx command should not be treated as a reproducible version pin.

Remove the package and clean up integrations separately

To remove a global npm installation:

npm uninstall --global tokentracker-cli

This does not establish that a running server has stopped, that stored usage has been deleted, or that external coding-tool configuration has been restored. An npx-only launch also does not imply a global installation exists to uninstall.

For integration cleanup, compare current settings with the private pre-installation backup. Remove only the TokenTracker-specific hook or notification entry you can identify. Preserve unrelated Claude Code hooks and Codex TOML settings. Restore an entire backup only if it would not erase subsequent changes. For passive readers, do not delete the source tool’s logs or database merely to disable TokenTracker.

A verified universal cleanup command and data-removal procedure are not specified here. If you cannot identify an integration entry confidently, stop and consult the matching release instructions rather than deleting configuration files. After cleanup, run a normal coding-tool session and confirm it does not report a missing notification executable.

Require access control before any public tunnel

Project names, model choices, usage volume, cost estimates, working hours, and provider limits can be private even when prompts are not displayed. A generated hostname is not an authorization policy. HTTPS protects browser transport to the public endpoint but does not decide who may retrieve the dashboard.

Before extending this setup, select a documented application authentication method or a trusted access-control gateway suitable for your environment. It must protect the full application surface, including APIs and live connections, and must not leave an alternate unprotected route. If using a separate gateway, the tunnel target must be that protected gateway rather than the raw dashboard port.

Validate protection locally before public activation:

1. Open the protected entry point without credentials or an authenticated session.
2. Confirm that the page requires authentication or is denied.
3. Request actual dashboard data URLs without credentials. Verify denial or authentication redirection with no private data in the response.
4. Sign in as an authorized user and confirm that the page and its data requests work.
5. Sign out and repeat the direct data requests to ensure authorization is not just a front-end screen.

A login page that hides navigation while leaving JSON endpoints readable fails this gate. So does a setup that authenticates one hostname but forwards another route directly to the backend. Until protection passes these checks, stay local.

Plan Localtonet access only after the security gate passes

For an approved protected deployment, consult our HTTP tunnel documentation for the current official configuration sequence. We intentionally do not substitute a generic lifecycle checklist for those setup instructions or provide an unprotected Start walkthrough here.

Our HTTP tunnel family is appropriate for a browser-based HTTP application. The local target is an IP address and port reachable from the connected client device. On the same machine, 127.0.0.1:7680 is the candidate raw TokenTracker endpoint only after the explicit local check above succeeds. It is not the correct public tunnel target if authorization lives in a separate gateway on another port.

Options and availability can vary by plan and current product configuration. Our client’s outbound connection avoids inbound router forwarding, firewall changes, VPN setup, and a public IP requirement, but it does not authorize bypassing organizational network policy.

Acceptance checks for a future protected public deployment

After an administrator has established protection and followed the official HTTP setup workflow, repeat the authorization tests through the assigned HTTPS URL from a separate network. Use a signed-out browser and requests without session credentials. Test the same data endpoints observed locally, not just the home page.

Then sign in as an authorized user, inspect the Network panel, and compare dashboard behavior with the local baseline. Check data responses, date filters, model and project views, and any live connection actually used by that version. Watch for requests still pointing at localhost, which would refer to the remote viewer’s machine, and for origin or mixed-content errors. Do not invent proxy headers or environment variables to conceal a failure.

Stop the tunnel immediately if unauthorized data is accessible. The public route is available only while the selected client is connected and the tunnel is running. Stop it when remote access is unnecessary; delete the configuration when it should not be reused. Stopping TokenTracker and stopping a tunnel are independent actions.

Troubleshoot the failing layer

Runtime or package installation fails

Compare node --version with the published engines value. If the runtime is incompatible, choose a maintained compatible release. If a new terminal still resolves an old Node.js installation, inspect your shell path or version manager. A missing engine field leaves compatibility uncertain; it is not a reason to ignore installation errors.

Port 7680 does not respond

Inspect startup output and identify the listener using your operating system’s tools. A port conflict may mean another application or a previous TokenTracker instance is already running. Do not terminate an unidentified process. This guide does not establish a supported TokenTracker port or bind-address override, so do not guess a flag.

The page loads but no usage appears

Check data requests first. If they succeed, inspect the integration and current user context. End a normal session for a session-end integration; check source availability for a passive reader. Compare configuration changes with your backup and ensure the selected date range covers the new activity.

A global command is missing

Check the package’s bin mapping before diagnosing a path problem. Confirm the package appears in the global npm listing. If the command exists in metadata but not in your shell, inspect the global prefix and path rather than switching package names.

A future public deployment loads only the page shell

Compare local and public data requests. Check the selected client, protected target address, tunnel state, and gateway authorization. A page returning successfully while APIs fail is not a completed deployment. Record request status and browser errors without disclosing tokens, cookies, private URLs, or usage bodies.

Unexpected public access is possible

Stop the tunnel first. Check whether authorization covers all paths and whether the tunnel accidentally targets the unprotected backend. Reopen access only after unauthenticated page and data requests are denied and authorized requests work.

Frequently asked questions