//DOCS Trial Setup

Self-Serve Trial Setup

For the shortest verified setup—provider choice, app-pinned observe key, one request, and diagnostics—start with the 5-Minute Quickstart.

This guide is for new hosted users starting a 30-day Punk Pro trial from https://punktechnologies.com/signup.

The trial path is:

1. Create an account.
2. Verify your email.
3. Create an API key.
4. Route one agent call through Punk.
5. Review the trace, cost, policy, and route explanation.

No OTP code is required. Signup uses email and password. Pro trial limits become effective after the org owner verifies their email.

No credit card is required. When the trial ends, Punk returns the workspace to the Free plan (10,000 gateway runs per month) unless the owner chooses Pro ($99 per month). There is no automatic charge at trial expiry.

1. Start the Trial

Open:

https://punktechnologies.com/signup

Enter your work email, then continue to the hosted app signup form.

The signup form asks for:

On success Punk creates:

• a user account,
• a private organization for that user,
• owner membership in that organization,
• a 30-day Pro trial on that organization,
• a browser session so the user lands in the dashboard.

2. Verify Email

Open the email from Punk with subject:

Verify your email for Punk

Click the verification link. The link calls:

GET /api/v1/auth/verify/:token

Before verification, the organization stores the Pro trial, but billing views show the effective plan as Free with status verification_required. This is intentional. After verification, the remaining trial window activates Pro quotas and Pro-only serving behavior.

If the email does not arrive, check spam/quarantine and confirm the address was typed correctly. If it still is not present, contact Punk support so the delivery event can be checked in Resend.

3. Confirm Trial Status

In the dashboard, open Usage. A verified trial org should show:

• plan pro,
• status trialing,
• trial end date about 30 days after signup,
• Pro quota limits.

The API shape is:

curl https://app.punktechnologies.com/api/v1/usage \
  -H "Authorization: Bearer $PUNK_API_KEY"

Browser sessions can also read this endpoint through the dashboard cookie.

4. Create an API Key

Open the dashboard:

https://app.punktechnologies.com

Go to Governance, then API keys.

Create a key for the first app:

Copy the pk_... token immediately. Punk stores only its hash, so the token is shown once.

Use observe mode for the first real traffic. Observe mode traces live behavior and shows what Punk would have optimized without serving shortcuts or blocking work.

5. Connect an OpenAI-Compatible Client

If your app already uses an OpenAI-compatible client, change only the base URL and API key:

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-agent",
    "X-Punk-Agent": "triage-worker",
    "X-Punk-Subject": "user-123"
  }
});

const completion = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Summarize this customer issue." }],
});

Helpful identity headers:

These dimensions keep costs, traces, caches, and policy decisions attributable.

6. Connect an Anthropic-Compatible Client

For Anthropic-compatible clients, point the client at the Punk gateway origin and use the Punk API key as the bearer token. The wire endpoint is:

https://app.punktechnologies.com/v1/messages

Minimum request:

curl https://app.punktechnologies.com/v1/messages \
  -H "Authorization: Bearer $PUNK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Anthropic-Version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "hello"}]
  }'

7. Add The TypeScript SDK

Install the published SDK:

npm install @punktechnologies/sdk

Minimal call:

import { Punk } from "@punktechnologies/sdk";

const punk = new Punk({
  baseUrl: "https://app.punktechnologies.com",
  apiKey: process.env.PUNK_API_KEY,
  app: "support-agent",
  agent: "triage-worker",
});

const result = await punk.chat({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Classify this ticket: password reset failed." }],
});

console.log(result.runId, result.route, result.content);

Use:

PUNK_API_KEY=pk_...

The SDK baseUrl is the gateway origin, not /v1.

8. Confirm the First Run

After one request, open the dashboard:

• Overview shows total runs and spend.
• Runs shows each request with route, cost, latency, provider, model, and run id.
• Run detail shows the trace ledger and route explanation.
• Governance shows policy and audit events.
• Usage shows quota and plan status.

Responses also include:

9. Add Provider Keys If Needed

Hosted Punk can use platform providers when configured. If your org wants to bring its own model provider keys, add them in Governance, Provider keys.

Common provider names:

Provider keys are stored in the encrypted credential vault and are never returned by the API.

10. Invite Teammates

Open Governance, Organization.

Invite teammates by email and role:

Invite links prove the email address for the invited account.

11. Move from Observe to Optimize

Stay in observe mode until you have enough traces to judge repeated work.

Switch a key to optimize mode only when:

• the traffic pattern is understood,
• governance rules are acceptable,
• route explanations make sense,
• replay/shadow evidence is visible for generated artifacts,
• the team is comfortable with the serving behavior.

You can keep one observe key and create a separate optimize key for staged rollout.

Troubleshooting

Related Docs

• Accounts & Orgs
• SDK
• API
• Billing & Usage
• Governance
• Troubleshooting