Skip to main content
Run this from the root of the repository you want to trace:
Setup needs Node.js 20.12 or later and a Python or TypeScript/JavaScript application. Using a coding agent? Coding agents has a prompt to paste. Prefer to add the SDK yourself? Skip to Set up manually.

What setup does

Setup checks for uncommitted changes, signs you in through your browser, selects or creates a project, and sets TRACEROOT_API_KEY for your application, normally in .env.local or .env. It then runs your coding agent and waits for a trace, or gives you a task or manual steps to finish yourself. Setup never reverts your coding agent’s edits, so review them with git diff. It keeps its progress and a project key for the CLI in .traceroot/, which it git-ignores. In a monorepo, run setup from the service’s directory or pass --service <path>. For every option, run npx -y traceroot-cli@latest setup --help. Your deployed application also needs TRACEROOT_API_KEY in its environment, plus TRACEROOT_HOST_URL if you self-host.

Self-hosted traceroot

Pass your API’s origin as --host, and your web app’s origin, where you sign in, as --auth-host. For a local deployment with the default ports:
Use origins only, without /api/v1. If both share one origin, --host alone is enough. Your deployment’s Traces page shows this command with its origins filled in. See Self-Hosting to run a deployment.

Set up manually

These are the steps setup automates.

1. Get an API key

Create an API key either with traceroot Cloud or Self-Hosting.

2. Install the SDK

3. Set environment variables

traceroot Tracing page with the Create an API key step highlighted

Tracing setup: sidebar, Manual tab, API key field, Generate button

Neither SDK loads .env files automatically; both read the process environment. Export the variables in your shell:
(If you prefer to use a .env file, ensure you load it explicitly in your code as shown in the next step.)

4. Instrument your code

Initialize traceroot where your application starts, inside the if __name__ == "__main__": block rather than at module scope, so a test that imports the module doesn’t send traces.
Under a server such as uvicorn or gunicorn that block never runs, so initialize where the framework starts up.
Run your own tests with TRACEROOT_ENABLED=false so they don’t send traces either. For full SDK details, see the Python SDK or TypeScript SDK.

5. See your first trace

Run your application and exercise the code you instrumented. Open traceroot Cloud (or your self-hosted dashboard), navigate to your project, and you’ll see the full span hierarchy, token usage, cost, and timing. Prefer the terminal? The traceroot CLI works with the same traces, plus detector findings and evaluations, from your shell.

Troubleshoot

Setup stopped partway

Ask setup what went wrong, then continue from where it stopped:
If you ran setup with --service <path>, pass the same option to both. If your coding agent didn’t finish, setup keeps its output in .traceroot/setup-instrument-output.log. That file can quote your repository’s files, secrets included, so check it before you share it.

No trace arrived

Run your application once and exercise the instrumented code, then run npx -y traceroot-cli@latest setup --resume. Neither SDK loads .env on its own, so check that your application loads the file setup wrote, or export the variables in your shell.

Still stuck?

Ask on Discord or open an issue.

Next steps

Python SDK

Full API reference for the Python SDK.

TypeScript SDK

Full API reference for the TypeScript SDK.

Features

Attach users, sessions, tags, metadata, and more to your traces.

Detectors

Create your first detector and start surfacing failures in your traces.

traceroot Agent

Auto-debug failing traces with the traceroot Agent.

CLI

Work with your traces, findings, and evaluations from the terminal.