Quickstart

Connect a Node.js server with the guided installer and confirm a real model call was recorded.

On this page

The installer detects your framework and package manager, connects the project through your signed-in browser, previews every file it will change, installs the SDK, and then waits for a real model call from your application. It needs Node.js 20 or newer to run; your application can stay on Node.js 18.

Run the installer in your application

Run this in the package that actually makes your model calls — not in the repo root of a monorepo, unless that is where the server lives.

Terminal

npx --yes @tracehatch/cli@0.3.0 init

The installer looks for supported packages under the usual apps, packages, services, server and backend folders. If it finds more than one it asks which to use; --yes never guesses. Use --cwd apps/api to choose directly.

Authorize it in your browser

The installer opens your browser, where you pick the project and environment. Use a development key while you experiment.

The browser shows a confirmation code, never the key. The installer exchanges a one-time device secret for the ingest key and writes it to your private environment file. No key is ever passed as a command-line argument or a URL.

Choose whether to record prompts and outputs

Guided setup starts with prompt and output capture off. You can opt in after reading what would be collected. The answer is written as TRACEHATCH_CAPTURE_BODIES beside your key, so changing your mind later needs no code change, and a rerun keeps your previous choice.

Pass --no-capture-bodies or --capture-bodies to answer up front.

Review the file changes

Nothing is written until you accept the preview. For most applications the whole integration is one line:

Any Node server — --import @tracehatch/sdk/auto is added to the start/dev script you already have, keeping its entry file and arguments. Scripts behind cross-env, nodemon, tsx, ts-node and ts-node-dev are recognised.
Next.js — root or src instrumentation beside app/pages, guarded to the Node.js runtime. An existing register() function is extended, not replaced.
NestJS — import "@tracehatch/sdk/auto" as the first line of src/main.ts.

Anything the installer will not edit safely — a custom launcher, a nonstandard NestJS entry, a script already using --require — is reported as an exact instruction to apply by hand. The rest of setup still completes.

Trigger a real AI action

init waits up to 90 seconds for the first real model call from your app, and exits non-zero if none arrives. Restart your server, use one AI feature you already have, and let it finish.

#Open the run

Open Traces in your project and find the run you just triggered. Confirm it is the action you performed, then open it: the waterfall shows what called what, and a model step shows its duration, reported tokens, errors and cost where pricing is available.

Reading a trace walks through the view.

#Useful flags

Common variationsTerminal

tracehatch init --dry-run --cwd apps/api   # preview only; never writes or authenticates
tracehatch init --no-capture-bodies        # answer the privacy question up front
tracehatch init --yes --wait 0             # unattended: no prompts, no waiting

--dry-run never authenticates, creates a key, installs a package or writes a file, and hides every environment value in its preview. Full flag reference: CLI.

#Re-check and undo

Check this application againTerminal

npx --yes @tracehatch/cli@0.3.0 doctor

doctor sends a diagnostic without calling an AI provider, then reports two separate things: whether the connection is verified, and whether a model-call trace from your application arrived after it. --wait 60 waits for that application call.

Reverse every change init madeTerminal

npx --yes @tracehatch/cli@0.3.0 uninstall

uninstall previews the diff first and reverses exactly what init added — the preload flag, the auto import, the instrumentation block and Tracehatch's own environment names. A file you edited by hand is reported rather than rewritten. The SDK dependency and the project key are left for you to remove and revoke deliberately.

#If the installer is not right for you

Your server is not Node.js → Provider gateway or Log endpoint.
You would rather make the changes yourself → Manual installation.
You are in CI → set TRACEHATCH_API_KEY in the environment and init skips browser approval entirely. Combine with --yes, --cwd and --wait 0.