> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebench.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK quick start

> Connect production traffic from your Node.js application.

<Note>The SDK is a preview. Use the installation source provided by Bench; a public npm release is not available yet.</Note>

## Set up with your coding agent

<Steps>
  <Step title="Open SDK in Bench">
    Open **SDK** in the sidebar, or **Production → Set up SDK** inside a system.
    Enter your repository and branch, then select **Create setup key**.
    SDK access is included on every plan.
  </Step>

  <Step title="Copy the agent prompt">
    Review the prompt shown in Bench, then select **Copy agent prompt**.
    Paste it into Claude Code, Cursor, Codex, or another trusted coding agent in your application repository.
    The prompt includes a one-time key, the installation source and your API endpoint.
    Use a trusted agent: that prompt contains a secret. Do not commit or share it.
    The key is shown only for this setup session. Copy it before leaving the page.
  </Step>

  <Step title="Verify an interaction">
    The agent adds server-side instrumentation and sends a synthetic metadata-only
    trace. Open **AI systems**, select the declared runtime system, then **Production**.
  </Step>
</Steps>

The setup key is scoped to one repository, has no team-wide read access and has
a zero evaluation cap. Creating it does not start a paid evaluation. Manage or
revoke it from **SDK → Manage keys**.

## Install manually

Build the local `bench-sdk` checkout with `npm ci && npm test && npm pack`, then:

```sh theme={null}
npm install /absolute/path/to/trybench-sdk-0.1.0.tgz
```

```ts theme={null}
import { Bench } from '@trybench/sdk'

const bench = new Bench({
  apiKey: process.env.BENCH_API_KEY!,
  repository: process.env.BENCH_REPOSITORY!,
  branch: process.env.BENCH_BRANCH!,
  endpoint: process.env.BENCH_API_BASE_URL,
  systemName: 'Support agent',
  captureContent: false,
})

const result = await bench.trace(
  { name: 'Answer customer', kind: 'LLM' },
  () => yourExistingModelCall(),
)
```

Use Node.js 20+ on the server. Never use public environment-variable prefixes
such as `NEXT_PUBLIC_` or `VITE_` for the key. The default endpoint is the API's
existing origin; always set `BENCH_API_BASE_URL` explicitly for this preview.
Use `https://api.staging.usebench.ai` for staging or `http://127.0.0.1:8080` locally.
Do not send staging keys to production. The staging installer is a commit-pinned
Git source from a private repository and requires GitHub repository access.
There is no public npm package yet.

## What Bench recognizes

`systemName` declares a runtime boundary. If omitted, the repository name is used.
The first trace creates a runtime system for that name, repository and branch.
This is observed runtime structure, not a verified business-purpose inference.
GitHub scans or uploaded prompts still provide the prompt definitions needed for
prompt benchmarking. SDK-only runtime systems can receive and display traces
before those definitions are connected.

Use nested `bench.trace` calls for agents and tools. The SDK preserves parent IDs.
Pass a real `componentId` from Bench to connect a span to a discovered prompt, or
link it from Production. Do not invent component IDs.

## Frameworks

Wrap your existing Node/server call for AI SDK, Mastra, OpenAI Agents or a custom
workflow. This release does not automatically patch those libraries. It is not
an OTLP collector, Python SDK, browser SDK or a guarantee of complete agent tracing.

For a reusable coding-agent guide, see `skills/bench-sdk/SKILL.md` inside the
local package. Follow [production checks](/sdk/production-checks) when ready to evaluate.

## Find your activity

Open an AI system's **Production** tab. Recent interactions appear after the SDK sends them. The **Quickstart** button opens this guide in a new tab; **Set up SDK** opens the in-app setup. Capturing metadata does not start an evaluation.