Quickstart - Firedog

Firedog sits in front of your existing LLM calls. You keep calling an OpenAI-compatible endpoint; the only change is the base URL (your in-VPC collector) and a little attribution context. The collector forwards the call to the upstream provider, prices it, writes the full record to Postgres in your VPC, and emits metadata to the dashboard.

This page assumes a collector is already reachable at a URL like https://collector.internal. For the split-plane picture — what stays in your VPC versus what reaches the cloud — see How it works and Security.

Your provider API key is forwarded by the collector to the upstream provider so the call can complete. It is used to authenticate to the provider and is never sent to Firedog cloud. See /security.

Prerequisites

A reachable collector

A collector running inside your VPC, exposing POST /v1/chat/completions. Note its URL.

An upstream provider key

The API key for whichever provider backs the models you call. The collector forwards it upstream; store it as an environment variable rather than inlining it.

A model string

One of the models Firedog prices — for example opus, sonnet, haiku, gcp/gemini-2.5-pro, gcp/gemini-2.0-flash-lite, or cerebras/llama3.1-8b.

Choose a path

SDK (@firedog/sdk)
Drop-in proxy (any OpenAI SDK)

The SDK mirrors the OpenAI client surface. You create a client pointed at your collector, set attribution defaults once, and pass per-call context on each request.

Install

npm install @firedog/sdk

pnpm add @firedog/sdk

yarn add @firedog/sdk

Create a client

Point collectorUrl at your in-VPC collector. apiKey is forwarded to the upstream provider. defaultContext is attribution applied to every call from this client.

import { createClient } from "@firedog/sdk";

const firedog = createClient({
  collectorUrl: "https://collector.internal", // your in-VPC collector
  apiKey: process.env.PROVIDER_KEY,           // forwarded to the upstream provider
  defaultContext: { team: "macro-desk" },     // attribution on every call
});

Make a priced, attributed call

Add per-call context to file this specific call under a workflow (and, optionally, a user).

const res = await firedog.chat.completions.create({
  model: "opus",
  messages: [{ role: "user", content: "Summarise today's macro prints." }],
  context: { workflow: "market-research", userId: "u_123" },
});

console.log(res.callId);                         // ULID correlating VPC record ↔ cloud metadata
console.log(res.choices[0].message.content);
console.log(res.usage.prompt_tokens, res.usage.completion_tokens);

A returned callId means the call was priced and recorded. It should appear on the dashboard Home view attributed to macro-desk / market-research shortly after.

No Firedog package required. Point any OpenAI-compatible client at the collector’s base URL and carry attribution in x-firedog-* headers.

Swap the base URL

Set base_url to the collector’s /v1 and pass your provider key as the API key — the collector forwards it upstream. Send attribution as default headers.

from openai import OpenAI

client = OpenAI(
    base_url="https://collector.internal/v1",  # your in-VPC collector
    api_key=os.environ["PROVIDER_KEY"],         # forwarded to the upstream provider
    default_headers={
        "x-firedog-team": "macro-desk",
        "x-firedog-workflow": "market-research",
        "x-firedog-user": "u_123",
    },
)

res = client.chat.completions.create(
    model="opus",
    messages=[{"role": "user", "content": "Summarise today's macro prints."}],
)
print(res.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://collector.internal/v1", // your in-VPC collector
  apiKey: process.env.PROVIDER_KEY,          // forwarded to the upstream provider
  defaultHeaders: {
    "x-firedog-team": "macro-desk",
    "x-firedog-workflow": "market-research",
    "x-firedog-user": "u_123",
  },
});

const res = await client.chat.completions.create({
  model: "opus",
  messages: [{ role: "user", content: "Summarise today's macro prints." }],
});
console.log(res.choices[0].message.content);

Or call it directly with curl

The endpoint is OpenAI-compatible, so a raw request works too. Attribution rides on the same headers.

curl https://collector.internal/v1/chat/completions \
  -H "Authorization: Bearer $PROVIDER_KEY" \
  -H "Content-Type: application/json" \
  -H "x-firedog-team: macro-desk" \
  -H "x-firedog-workflow: market-research" \
  -H "x-firedog-user: u_123" \
  -d '{
    "model": "opus",
    "messages": [{"role": "user", "content": "Summarise today'\''s macro prints."}]
  }'

Set x-firedog-call-id yourself (a client-minted ULID) if you want to correlate the call in your own logs before the response returns. Omit it and the collector mints one. Either way the id links the full VPC record to the cloud metadata.

What just happened

Priced

The collector priced the call from the shared pricing table using the model and token counts — no vendor invoice reverse-engineering required.

Attributed

Your team / workflow (and salted userHash) landed on the call, so it rolls up per desk and workflow on the dashboard.

Recorded in your VPC

The full record — prompt messages, any RAG chunks, and the response — was written to Postgres inside your VPC and never left it.

Metadata to the cloud

Only CallMetadata (ids, model, tokens, cost, latency, labels) reached the dashboard. No prompt or response content.

Next steps

Attribution

Model the team, workflow, and userId context so every dollar files under the right desk and run.

Security

See exactly what stays in your VPC, what the metadata contains, and how SensitivityProfile controls it.

​Prerequisites

​Choose a path

​What just happened

Priced

Attributed

Recorded in your VPC

Metadata to the cloud

​Next steps

Attribution

Security

Prerequisites

Choose a path

What just happened

Next steps