Skip to content

Agent setup

This page is an instruction to a coding agent (Claude Code, Codex, Cursor or any other) that a person has asked to set Tracepad up for the project in front of it. A person reading it learns what the agent will do and what it will ask of them. The quickstart covers the same ground by hand.

The goal: a Tracepad server running on this machine, the project's application sending its traces to it, a trace you have read back yourself, and a report to the person. Work in order. Each step says what a healthy answer looks like. Anything else is a reason to stop and tell the person, not to improvise.

1. The binary

tracepad version

A release (0.1.0) or a release candidate (0.1.0-rc.1) means it is installed: go to step 2. dev is a build from a checkout, which serves but has no container image: keep it for the binary path, or install a release. command not found means installing the binary and the agent skill, together, verified, with no sudo:

curl -fsSL https://tracepad.github.io/tracepad/install.sh | sh

Healthy output ends like this:

installed tracepad 0.1.0 at /home/you/.local/bin/tracepad
  verified  sha256 matches checksums.txt; attestation not checked: gh is not installed
  skill     installed 0.1.0 to /home/you/.claude/skills/tracepad

Next, paste this into your coding agent (Claude Code, Codex, Cursor, …):

  Set up Tracepad for this project: follow https://tracepad.github.io/tracepad/agent-setup.md
  • there is no stable release of Tracepad yet: the message names the newest release candidate and the line that installs it, with TRACEPAD_VERSION. Run that line.
  • ~/.local/bin is not on your PATH: call the binary as ~/.local/bin/tracepad for the rest of this session. Adding the directory to the person's shell profile is theirs to do.
  • Another tracepad comes first on your PATH: an older binary shadows the new one. Call the new one by its full path for the rest of this session, and report the other.
  • Any other line starting tracepad install: is a failure, with its reason. Nothing was installed. Report it rather than working around it: a checksum or an attestation that does not match is never retried with the check turned off.

The variables the script reads are in configuration.md.

2. The procedure

The rest of the steps, with their commands and their healthy answers, are in the agent skill the binary carries. Its version matches the binary's, so the commands are the ones this version has. Print it and follow it:

tracepad skills show setup.md

If your agent loaded the tracepad skill, this is the same file as its references/setup.md. A binary older than this page (0.1.0-rc.1) answers the skill has no file "setup.md". Read the file from the repository instead, and install the skill again once a newer binary is in place:

curl -fsSL https://raw.githubusercontent.com/tracepad/tracepad/main/agent/skills/tracepad/references/setup.md

In outline:

  1. Is there a server? tracepad health. A server you did not start means asking the person for its URL and a key, and starting no second one.
  2. Look at the project, and choose how it will send (the table below).
  3. Start a server and declare its key (on 4318, or a free port when something else holds it), but only when you start it now, on loopback, on a data directory with no database yet. The key goes from the generator into .env, never onto the screen, after .env is confirmed ignored by git. On any other server the key comes from the person.
  4. Send a test span with curl. 200 means it is stored.
  5. Connect the application and run one path that calls a model.
  6. Read both back with tracepad traces ls and tracepad traces last.
  7. Report (below).

Choosing the path

What the project already has decides how it sends. One exporter per process, so look before you add (tracepad skills show instrumenting.md, sections 1 and 2):

The project has It sends through The shapes are in
OpenTelemetry already, in any language its own exporter, configured by environment alone (OTEL_EXPORTER_OTLP_*) ingest.md
The Langfuse SDK the same SDK, pointed at Tracepad (LANGFUSE_*) langfuse-sdk.md
Neither, in Python (pyproject.toml, requirements*.txt) the tracepad package sdk-python.md
Neither, in Node (package.json, Node 22 or newer) the tracepad package sdk-js.md
Neither, in Go (go.mod) the tracepad module sdk-go.md
Neither, in another language that language's OpenTelemetry SDK over OTLP/HTTP ingest.md

With Docker instead of the binary

When the person asks for Docker, the server runs as a container and the binary is still installed, for its CLI and its skill. It is the same procedure with how=docker in step 3's start command (tracepad skills show setup.md): a container and a volume named after the project, the port published on loopback alone, and the image of the binary's own release. A development build (tracepad version says dev) has no image, so install a release first. A declared key is part of the container's configuration, so whoever can run docker inspect on this machine can read it: say so in the report. docker.md covers the volume and upgrades.

What needs the person

You ask for these and do not do them yourself:

  • A model provider's API key (OPENAI_API_KEY and its kin), for the run of step 5. You do not look for one in files or history.
  • A Tracepad key for a server you did not start.
  • Making the server reachable from other machines (--listen :4318, a proxy, TLS): it speaks plain HTTP (docker.md).
  • Creating the account in the browser, through the setup link.
  • Anything that deletes: traces, a project, a data directory, a volume.
  • Keeping the server running past this session: a service (install.md) or a container with a restart policy.
  • Replacing a variable that pointed somewhere else (Langfuse Cloud, another collector), because the application stops sending there.

The report

The person reads this, not your transcript. It says:

  • Where to look: the setup link from the server's log, which they open to choose an email and a password. After that, the server's address, the TRACEPAD_URL in .env.
  • Where the key is: .env, as TRACEPAD_API_KEY and the lines you added, for which project. Before production each application gets its own ingest-only key (Settings → Project → API keys).
  • The server: that you started it, its PID file and log, how to stop it, and that it does not outlive a reboot.
  • What you changed: every file, .gitignore included, and the test trace tracepad-setup-check.
  • What is left for them: the items above that apply, and anything that did not pass, with the answer you got.