//DOCS First Run

Punk in 30 Minutes

Need only the first hosted request and its diagnostics? Start with the 5-Minute Quickstart. This guide continues with the longer observe-first path and persona-specific rollout.

The first useful Punk experience is deliberately small:

1. Connect one existing agent or model client.
2. Send one real, low-risk request.
3. Open the run and understand why Punk chose its route.
4. Confirm the policy decision and choose the next action.

Do that before configuring connectors, building workflows, tuning learning, or enabling automatic optimization. Punk earns trust from real execution evidence; a large setup does not create better evidence.

For a production pilot or complete rollout path, continue with the Onboarding Guide.

Recommended Enterprise Start

Start with one representative application and an observe mode key. Choose traffic that is frequent enough to learn from, inexpensive enough to repeat, and low-risk enough that the first run cannot create customer harm.

Avoid write-heavy or irreversible workflows at first. The first milestone is not “Punk optimized something.” It is “the team can see and explain what happened.”

0-5 Min: Connect To Hosted Punk

Open the hosted dashboard:

https://app.punktechnologies.com

In Governance → API keys, create a tenant key in observe mode. Copy the token when it is shown; Punk stores only its hash.

export PUNK_BASE_URL=https://app.punktechnologies.com
export PUNK_API_KEY=pk_...

An existing OpenAI-compatible client needs only two changes:

• Base URL: https://app.punktechnologies.com/v1
• API key: the Punk tenant key

Keep the model, messages, and application behavior unchanged. Send these identity headers on every request:

5-Minute Developer First Run

Send one deterministic, low-risk request:

curl -sS -D /tmp/punk-headers -o /tmp/punk-body \
  "$PUNK_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $PUNK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Punk-App: support-app" \
  -H "X-Punk-Agent: support-agent" \
  -H "X-Punk-Subject: ticket-123" \
  -d '{
    "model": "gpt-4o-mini",
    "temperature": 0,
    "messages": [
      { "role": "user", "content": "Classify this ticket: I was charged twice. Return JSON." }
    ]
  }'

RUN_ID=$(awk 'tolower($1)=="x-punk-run-id:" {print $2}' /tmp/punk-headers | tr -d '\r' | tail -n 1)
ROUTE=$(awk 'tolower($1)=="x-punk-route:" {print $2}' /tmp/punk-headers | tr -d '\r' | tail -n 1)

printf 'route=%s runId=%s\n' "$ROUTE" "$RUN_ID"
jq -r '.choices[0].message.content' /tmp/punk-body

The response should include both x-punk-run-id and x-punk-route. The first route is normally live; that is the safe and expected result before Punk has evidence for a cheaper path.

Now read the stored explanation:

curl -sS \
  -H "Authorization: Bearer $PUNK_API_KEY" \
  "$PUNK_BASE_URL/api/v1/runs/$RUN_ID" \
  | jq '{
      route: .run.route,
      provider: .run.provider,
      costUsd: .run.costUsd,
      latencyMs: .run.latencyMs,
      explanation: .run.routeExplanation
    }'

In the dashboard, open Runs, select the new run, and answer four questions:

1. Did Punk receive the intended app, agent, and subject identity?
2. Which route served the response, and why?
3. What alternatives did Punk reject?
4. What policy decision and side-effect evidence were recorded?

If those answers are clear, the first run succeeded.

What To Do Next

Repeat the same safe request once. In optimize mode an eligible deterministic request may use the exact cache; in observe mode Punk continues serving live and records the optimization it would have used.

Then choose one next action based on evidence:

Path A: Chat User Or Evaluator

Use Chat when you want to experience Punk without changing application code.

1. Start one conversation with a concrete task.
2. Send the message and open the linked run.
3. Read the route explanation, cost, policy decision, and trace.
4. Save the conversation as an agent only if the prompt represents recurring work.

Do not judge learning from a one-off chat. Learning becomes meaningful when similar real requests recur.

Read Chat & Agents when you are ready to turn a useful conversation into a reusable agent.

Path B: Workflow Builder

Build a workflow only when the work actually has multiple steps, tools, or decision branches. A single model request does not need a workflow wrapper.

Start from one template, run it with representative input, and inspect the node timeline. Confirm that:

• Each node has a clear purpose.
• Tool calls use declared arguments and side-effect levels.
• Risky actions are dry-run, held, or approval-gated.
• The final output and route evidence are understandable.

Then read Workflows. Use Connectors only when the workflow needs a real external system.

Path C: App Developer

Keep the integration boring: preserve the provider-compatible request shape and point the client at Punk.

For OpenAI-compatible clients:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://app.punktechnologies.com/v1",
  apiKey: process.env.PUNK_API_KEY,
  defaultHeaders: {
    "X-Punk-App": "support-app",
    "X-Punk-Agent": "support-agent",
  },
});

For Anthropic-compatible clients, use the gateway origin https://app.punktechnologies.com and a Punk key; Anthropic SDKs append /v1/messages themselves. Punk also accepts one duplicated /v1 prefix for clients that already configured the versioned base URL.

Add SDK tool tracing only when your application actually executes tools. A tool contract should state its name, JSON arguments, side-effect level, and subject scope. Unknown tools default conservatively.

Use feedback after you can associate a user judgment with a specific run. Positive feedback strengthens evidence; corrections and flags should be precise enough to explain what was wrong.

Read SDK for client helpers and API Reference for the complete wire surface.

OpenAI-Compatible Apps

Use /v1/chat/completions. Punk returns standard OpenAI response bodies plus x-punk-run-id and x-punk-route response headers.

Anthropic-Compatible Apps

Use /v1/messages. Punk preserves Anthropic error envelopes, tool-use responses, streaming events, and token counting.

Read The First Route Explanation

The route explanation is the primary integration receipt. It should name the selected path, rejected alternatives, fallback behavior, savings evidence, and relevant policy decision.

Add Tool Tracing When It Matters

Trace tools when their results, cacheability, or side effects affect correctness. Do not wrap ordinary local helper functions merely to produce more telemetry.

Close The Loop With Feedback

Attach feedback to the run that produced the output. Prefer a concrete correction over a generic negative rating when the user can explain the failure.

Path D: Operator Or Admin

The operator’s first job is to make the initial evidence trustworthy, not to configure every control.

Check these in order:

1. Readiness — auth, provider, database, worker, and credential posture.
2. Runs — identity, route explanations, errors, costs, and policy decisions.
3. Governance — API keys, users, policies, approvals, and side-effect declarations.
4. Learning — only after repeated representative traffic exists.
5. Artifacts — only after replay and shadow evidence exists.

Avoid enabling auto-promotion, broad connector writes, or production canaries during initial setup. Those are rollout decisions, not onboarding requirements.

Before serving model substitutions in production, review the post-promotion reference controls: model_substitution_reference_holdout_bps and model_substitution_reference_max_cadence.

Read Governance, Configuration, and Troubleshooting as the deployment matures.

How Optimization Is Approved

Punk does not optimize a request because it looks repetitive. It observes successful runs, groups stable patterns, synthesizes a candidate, replays it against history, shadows it against new traffic, and promotes it only when the evidence and policy gates allow it.

The safe sequence is:

observe → cache where safe → discover pattern → replay → shadow → approve/canary → route

Live fallback remains available when an optimized route is missing, invalid, or no longer trusted.

Hosted Tenant Quick Reference

What To Read Next

• Onboarding Guide: full production onboarding and team rollout.
• API Reference: gateway and management endpoints.
• SDK: TypeScript integration and tool tracing.
• Governance: policies, approvals, and side-effect controls.
• Troubleshooting: common setup and runtime problems.