What setup does
Setup checks for uncommitted changes, signs you in through your browser, selects or creates a project, and setsTRACEROOT_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:
/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
- Python
- TypeScript
3. Set environment variables

Tracing setup: sidebar, Manual tab, API key field, Generate button
.env files automatically; both read the process environment. Export the variables in your shell:
.env file, ensure you load it explicitly in your code as shown in the next step.)
4. Instrument your code
- Python
- TypeScript
Initialize traceroot where your application starts, inside the Under a server such as uvicorn or gunicorn that block never runs, so initialize where the framework starts up.
if __name__ == "__main__": block rather than at module scope, so a test that imports the module doesn’t send traces.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:--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 runnpx -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.