Setup

Part of Gateway → Developers.

The reporting views require the Enterprise plan. Choose how you want to use Forgebench:

You can use both. Signing in to Forgebench does not sign you in to Claude or ChatGPT, and session reporting alone does not route model requests through the gateway.

Install the CLI and sign in

1. Install the CLI

   macOS / LinuxWindows

   curl -fsSL https://raw.githubusercontent.com/seedlinglabs/forgebench-cli/main/install.sh | bash

   Check the installed version with forgebench --version.

2. Run setup

   forgebench setup

   Choose browser SSO or enter an API key privately if you need to sign in. Use the arrow keys and Space to select your coding tools, then press Enter. Enter the outcome numbers for Sync coding sessions, Use ForgeBench for model requests, or both. Approve model access in your browser when asked. Setup reuses an existing chat:write key without prompting. Review the changes and approve them. No --gateway flag or separate gateway command is needed.

3. Check the selected capture options

   Selecting Sync coding sessions installs the local collector. Plain interactive setup does not select native OpenTelemetry capture. Configure it separately if needed; see OpenTelemetry.

4. Run a session and check the result

   Restart any tool whose settings changed, then run a small task. Open Gateway → Developers → Personal → Activity to find captured sessions. If you enabled routing, check Activity → Routed requests too.

   forgebench setup --status
   forgebench doctor

   Setup completion means the configuration was applied. Reporting is verified only after the server reports uploads for that tool. A successful gateway inference test does not prove the coding tool loaded its settings.

Release channels

The installer uses the stable channel. This guide describes CLI 1.4.22 and later. Check forgebench --version before onboarding.

To opt in to preview on an official binary installation:

forgebench update --channel preview --install
forgebench setup

Source and package-manager installations must be updated through the method that installed them. See Update for release checks and installation options.

Your own subscription: capture with OpenTelemetry

Keep your subscription sign-in in the official coding tool. Forgebench uses its own reporting login to receive sessions; it does not need your vendor password or a provider API key for reporting.

To switch a tool to native usage export manually, use forgebench setup --tool claude_code --capture otel or the same command with --tool codex. Check for capture otel applied and restart the tool. Older sessions can still be uploaded with forgebench run --since 30d --push.

To keep local session context alongside native usage, choose combined capture:

forgebench setup --tool claude_code --capture both
forgebench setup --tool codex --capture both

Run the command for each tool you use. OpenTelemetry supplies usage; session sync adds the available repository, branch and session context. Setup preserves an existing exporter it does not own and respects the workspace capture policy. If it reports a conflict, resolve that before expecting capture to work.

Use --capture otel for native usage export alone, or --capture local for local session sync alone. OpenTelemetry alone does not supply all the context needed for task linking or session analysis.

For Cursor, GitHub Copilot, Antigravity and OpenCode, select session sync in setup. Cursor local history has no measured token usage. An administrator can connect Cursor's usage API or configure Cursor Enterprise OpenTelemetry; see Team configuration.

Direct subscription calls remain outside gateway routing and budget enforcement. Reported usage estimates are separate from your subscription bill.

Authorize model requests

Your workspace administrator supplies provider access and assigns your allowed models and budgets. You do not need to supply a personal provider API key when the workspace funds the requests.

In interactive setup, select Use ForgeBench for model requests. Setup reuses a matching chat:write credential or offers browser authorization. Approve access to save the key privately and configure the tool in the same run. If authorization is declined or unavailable, enter a key privately or leave the prompt blank to skip routing. Model credentials are saved separately from reporting sign-in. Ask your administrator for access if no key is available. See Gateway for saved credentials and scripted setup. A reporting credential does not grant model access.

A Forgebench API key: route through the gateway

In guided setup, choose Use ForgeBench for model requests, or run:

forgebench gateway install

Select a compatible tool and authorize a gateway key. Restart the tool, run a small task, then open Activity → Routed requests to confirm it reached Forgebench.

forgebench gateway status
forgebench gateway verify --forgebench-url https://api.forgebench.ai

For self-hosted deployments, use your own API URL. The verify command checks the deployment's routing contract without making a model call. A successful configuration or contract check is not proof that inference succeeded.

Routing a native subscription through the gateway is a separate, deployment- and client-dependent option. Use it only when Setup guide → Advanced: use an existing native subscription confirms support. Ordinary subscription sign-in plus reporting does not require that option.

Connect tasks and review usage

An administrator connects tracker projects and GitHub repositories under Setup → Configuration → Work sources. Ordinary session sync can associate captured sessions with tasks using selected tracker and repository evidence. You do not need to pick a task before every session.

Open Personal → Usage & costs → By task, or Team → Economics → By task if you have access. See Connect work sources for setup, linking and what the figures include.

Other ways to run setup

If capture stays pending, check forgebench setup --status and forgebench doctor. Confirm the account, workspace and capture policy before rerunning setup. Keep your existing tool credentials in place.

OpenCode requires version 2.x for the pinned plugin. Setup can offer opencode upgrade --major with your approval. If the version cannot be read, check the executable path shown by setup and run opencode --version in the same terminal. Multiple installations can leave an older executable first on PATH. A fresh OpenCode installation does not need an existing session database before setup installs the collector.

If you already route through Forgebench, keep your provider and model settings. Select session sync to add reporting. If reporting sign-in has expired or its key was revoked, sign in again; a working inference key cannot replace it.

For flags, exit codes and unattended installs, see the CLI reference.

Next