Quickstart: Send Your First Request to Caveman Cloud

This guide takes you from signing in to viewing your first trace in the Caveman Cloud console. You need an existing upstream model provider account (for example OpenAI) with an API key.

Fastest path: let your coding agent do it. In the console, open Getting Started, then Send one request, and choose the option where your coding agent does the wiring. Caveman Cloud gives you a prompt with your gateway URL and a fresh Cave key to paste into your agent. See Connect your coding agent and Automated AI setup. The manual steps below are the alternative.

Open your Caveman Cloud console in a browser and sign in. Invited members land directly in the project they were invited to.

Create a project

From the console, create a new project and name it. The project is the scope for all traces, keys, and workloads you will inspect.

Create a Cave API key

Go to Gateway, Connect and generate a Cave API key. Copy the key value and the gateway URL. The gateway URL is the origin for your installation, with no trailing slash. For example: https://gateway.caveman.so.

Keep the Cave API key secret. It authenticates you to Caveman Cloud. It is separate from your upstream provider key.

Set environment variables

Export the key and gateway URL in your shell. Keep your upstream provider key available separately.

export CAVE_API_KEY="cave_live_..."
export CAVE_GATEWAY_URL="https://gateway.caveman.so"
export OPENAI_API_KEY="sk-..."

Configure your client

Point your OpenAI client at the gateway with a base-URL swap. Send the upstream provider key in the x-cave-upstream-key header when it is not stored in Caveman Cloud.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CAVE_API_KEY,
  baseURL: `${process.env.CAVE_GATEWAY_URL}/openai/v1`,
  defaultHeaders: {
    "x-cave-upstream-key": process.env.OPENAI_API_KEY!,
    "x-cave-agent": "support-agent",
    "x-cave-workflow": "resolve-ticket",
  },
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello, Caveman" }],
});

console.log(response.choices[0].message.content);

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CAVE_API_KEY"],
    base_url=f"{os.environ['CAVE_GATEWAY_URL']}/openai/v1",
    default_headers={
        "x-cave-upstream-key": os.environ["OPENAI_API_KEY"],
        "x-cave-agent": "support-agent",
        "x-cave-workflow": "resolve-ticket",
    },
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello, Caveman"}],
)

print(response.choices[0].message.content)

curl "${CAVE_GATEWAY_URL}/openai/v1/chat/completions" \
  -H "authorization: Bearer ${CAVE_API_KEY}" \
  -H "x-cave-upstream-key: ${OPENAI_API_KEY}" \
  -H "x-cave-agent: support-agent" \
  -H "x-cave-workflow: resolve-ticket" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello, Caveman"}]}'

The x-cave-agent and x-cave-workflow headers label traffic for reporting. They do not grant access.

View the trace

Open Traces in the console and look for the request you just sent. You should see the model, tokens, latency, cost, and the agent and workflow labels you attached.

Next steps

Connect a Workload

Learn how to route production agent or application traffic through the Gateway.

Traces and Spend

Filter, search, and understand request-level cost and latency.

Query with SQL

Run read-only SELECT over your project’s requests, spans, and tool events.

Evaluations

Build test cases and evaluate candidate changes against your traffic.

⌘I

Get Started

Self-Driving AI

Core Concepts

Tutorials

Analytics

Governance & Billing

Help

Quickstart: Send Your First Request to Caveman Cloud

Next steps

Connect a Workload

Traces and Spend

Query with SQL

Evaluations

​Next steps

Connect a Workload

Traces and Spend

Query with SQL

Evaluations

Next steps