Quickstart

Hosted ShipGauge in about five minutes — ingest, eval, and gate

Get cost tracking and a pre-ship gate running on a side project.

Base URL: https://shipgauge.dev (self-host: use your own origin).

Prerequisites

A ShipGauge account (sign up)
Node.js 20+ (for SDK + CLI examples)
An OpenAI (or Anthropic) API key if you want live wrapping

1. Create a project

Open ShipGauge and sign in.
Create a project in onboarding (or New project).
Copy your ingest API key (sg_ingest_...) and project id — store them as secrets.

export SHIPGAUGE_API_KEY=sg_ingest_...
export SHIPGAUGE_PROJECT_ID=your-project-uuid
export SHIPGAUGE_BASE_URL=https://shipgauge.dev

2. Install the Node SDK

npm i @shipgauge/node openai

import OpenAI from "openai";
import { ShipGauge } from "@shipgauge/node";

const sg = ShipGauge.init({
  apiKey: process.env.SHIPGAUGE_API_KEY!,
  projectId: process.env.SHIPGAUGE_PROJECT_ID!,
  baseUrl: process.env.SHIPGAUGE_BASE_URL ?? "https://shipgauge.dev",
});

const openai = sg.wrapOpenAI(new OpenAI(), {
  defaultFeatureId: "chat",
});

await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello" }],
});

Only token/cost metadata is sent — not message content.

3. Confirm the first event

Open Project → Overview. You should see requests and spend for chat.

Or post a synthetic event:

curl -X POST "$SHIPGAUGE_BASE_URL/api/v1/events" \
  -H "Authorization: Bearer $SHIPGAUGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"feature_id":"chat","model":"gpt-4o-mini","input_tokens":500,"output_tokens":120}]}'

4. Add a smoke eval (optional but recommended)

npm i -D @shipgauge/cli
npx shipgauge init
# Edit .shipgauge/config.yml with api_key + project_id + base_url
npx shipgauge eval --suite smoke

5. Gate check

npx shipgauge gate check --suite smoke

Rules live in .shipgauge/gate.yml (pass rate, cost, latency). First successful run can establish a baseline.

6. Wire GitHub Actions

Add secrets SHIPGAUGE_API_KEY and SHIPGAUGE_PROJECT_ID, then use the ShipGauge GitHub Action / CLI with --status-check. See GitHub Gate.

Verify

Step	Where
Events landing	Overview
Eval uploaded	Evaluations
Gate failing a bad change	PR check ShipGauge Gate

Common issues

401 on ingest — wrong key prefix or revoked key; create a new key under Account → API keys.
No spend on Overview — confirm feature_id and that the request reached baseUrl.
Local hostnames — set baseUrl / SHIPGAUGE_BASE_URL explicitly; don’t assume localhost.