Skip to main content
Glassray watches your agent, catches what breaks, and helps you ship the fix. glassray setup is the set-and-forget way to get there: run one command in your agent’s repo, do a quick setup in your browser, and come back to a verified, watched account. The command is a launcher. It signs you in, hands the connecting — GitHub, traces, Slack — to a browser wizard, mirrors each step back to your terminal as you finish it, and then does the one thing that has to happen locally: wiring the tracing SDK into your code. It won’t call itself done until it has seen a real, correctly-tagged trace arrive. None of your source code ever leaves your machine — the CLI edits files locally (or hands a prompt to your own Claude Code) and only talks to Glassray over HTTPS.

​
One command

1

Sign in (terminal)

The CLI opens your browser to sign in (it also prints the link, so this works over SSH). Sign in — or sign up, and you’ll name your organization and become its admin. Your account key is saved to ~/.config/glassray/credentials.json, readable only by you, and never written into a committed file: .mcp.json refers to it only as ${GLASSRAY_TOKEN}.
Belong to more than one organization? The CLI shows a picker — choose one, or create a brand-new organization right there. (--org <name-or-id> still works on both glassray setup and glassray login, and is the way to choose in CI.)
2

Pick your project (terminal)

Next, the CLI asks which project this setup is for — prod, staging, demo, local — or creates a new one on the spot (just hit Enter to keep the default). Everything after this lands in that workspace: the GitHub and Slack connections, your trace source, and the onboarding itself. If your key is already bound to a project from an earlier run, the CLI tells you and skips the question.
3

Finish setup in your browser

A short wizard opens, in the browser where you’re already signed in — scoped to the project you just picked — and walks you through connecting everything:
  • Connect your code — install the Glassray GitHub App (read-only) and pick your repo.
  • Connect traces — either pull from a provider you already use (LangSmith, Langfuse, PostHog), or choose the SDK and Glassray wires it into your code from your terminal.
  • Notifications — connect Slack so you get pinged when something breaks (skippable).
When you finish, the wizard tells you to head back to your terminal.
4

Back in your terminal — live status + SDK

As each browser step lands, your terminal lights up: GitHub ✓ Slack ✓ Sources ✓. If you chose the SDK (or skipped traces), the CLI provisions your trace source in the project you picked earlier and confirms it — source created in project "staging". Then the CLI shows your ingest key and asks before it writes anything — say yes and it saves the key to your env file (it detects .env.local or .env, and gitignores it). Then it wires @glassray/tracing into your code — tagging every trace with the three things Glassray needs (glassray.customer / agent / flow).That happens locally. If it hands the work to Claude Code, the run is headless — Claude applies the change and exits back to your terminal, streaming its progress as it goes — and it can never git commit or git push: those are hard-blocked, so the change always lands uncommitted for you to review. (--run runs Claude Code without asking; --prompt-only just prints the prompt; --skip-instrument wires no code but still provisions your key.)
5

Confirm a trace lands

Run your agent once. The CLI keeps watching until a trace with the right tags shows up in Glassray, then prints the report. If nothing lands, it names the likely cause — wrong key, wrong endpoint, a missing flush(), or a filter dropping it. (If you’d rather check later, glassray verify --wait is the same gate on its own.)

​
What it leaves behind

  • Your ingest key as GLASSRAY_API_KEY in .env.local (or .env), gitignored — the key your agent uses to send traces. Only on the SDK path, and only if you said yes when it asked.
  • .mcp.json — so your AI assistant (Claude Code, Cursor) can use Glassray’s tools. The key is referenced as ${GLASSRAY_TOKEN}, never written in, so the file is safe to commit.
  • A small, reviewable change to your code — the SDK setup + tags — again, only on the SDK path.
Want your coding agent to run the loop for you later? glassray init drops the Glassray skill into .claude/skills/glassray and .agents/skills/glassray — an operating manual it can follow. No daemon, no commits, no lock-in. From here your day-to-day surface is Slack and your own Claude Code; the dashboard is optional.

​
Re-running is always safe

Re-run glassray setup any time. If your onboarding is already done, it skips the browser wizard entirely and goes straight to status — and, on the SDK path, the local wiring. Every step checks what’s already there, so just run it again is the universal recovery: no cleanup, no duplicate orgs, no duplicate sources.

​
CI / headless

First-time onboarding needs a browser — the connecting happens in the wizard. Two headless paths:
  • Already onboarded once (in a browser)? glassray setup --api-key <org-key> skips the browser and just does the local SDK wiring + verify.
  • Scripting from scratch? The genuinely headless pieces are the SDK ones — glassray instrument --prompt-only then glassray verify --wait (both take --api-key). To connect a trace source without a browser (CI / agents), use the MCP tools — connect_otlp_source / connect_pull_source — since glassray connect now just opens the dashboard.
The key comes from whichever you set, in order: the --api-key flag, then the GLASSRAY_TOKEN environment variable, then the saved credential. GLASSRAY_TOKEN is deliberately different from the SDK’s GLASSRAY_API_KEY ingest key, so a shell that exports one can never be mistaken for the other. See the command reference for every command and flag.