//DOCS Docs Home

Punk Documentation

Punk is the adaptive runtime for production AI agents. These public docs are for customers evaluating, integrating, administering, and operating Punk.

Recommended Starting Point

First Hosted Run

# 1. Start a trial and create a tenant API key:
#    https://punktechnologies.com/signup

npm create @punktechnologies/punk-agent@latest my-agent
cd my-agent
cp .env.example .env
# edit .env and set PUNK_API_KEY
npm install
npm run smoke
npm start

Success means the command prints a route, a runId, and a dashboard run URL. Open the hosted app at https://app.punktechnologies.com to inspect route explanations, traces, feedback, savings, and cache/artifact evidence.

Start Here

Documentation Map

• Architecture and Repository Layout: contributor-facing runtime boundaries and source ownership map.
• Enterprise Pilot: observe-only first traffic, first-week report, shadow pilot, canary, proof review, and expansion.
• Enterprise Security Review: trust-center-style package for data boundaries, retention, tenant isolation, credentials, provider keys, audit export, operations, rollback, and compliance review gaps.
• Evidence Contract: public specifications for route explanations, the artifact DSL, replay, shadow, promotion, side effects, economics, and claim evidence.
• 5-Minute Quickstart: signup, verification, app-pinned observe key, provider choice, one request, exact run lookup, and first-run diagnostics.
• Onboarding: one golden path from connection to first request, route explanation, and next action, followed by concise persona guidance.
• Self-Serve Trial Setup: hosted signup, email verification, API key creation, SDK setup, and first agent call for trial users.
• Onboarding Guide: extended pilot and rollout guide from workflow selection through production readiness.
• UX Principles: operational UX and docs principles for safe defaults, evidence review, and progressive disclosure.
• SDK: TypeScript client reference for chat, tools, feedback, web fetch, sessions, and admin reads.
• Agent Activation: fresh starter app, hosted smoke test, flagship examples, and SDK activation checklist.
• OpenAI-Compatible AI Gateway: route existing OpenAI SDK traffic through Punk with a base URL change.
• OpenRouter: route OpenRouter provider/model slugs through Punk's OpenAI-compatible gateway.
• Vercel AI SDK: use Punk with ai and @ai-sdk/openai-compatible.
• LangChain: use Punk with LangChain.js ChatOpenAI.
• Anthropic SDK: route Anthropic Messages traffic through Punk.
• Claude Code: launch Claude Code through Punk and add Punk runtime tools with MCP.
• Codex Launch: route Codex CLI and macOS desktop model steps through Punk's Responses runtime.
• Agent Observability & Tool Caching: trace tools, declare side effects, cache read-only results, and read evidence.
• API: HTTP endpoints, auth, identity headers, and response conventions.
• Connectors: 51 managed SaaS connectors, 517 governed tools, install API, auth requirements, input contracts, side-effect levels, cache/replay/shadow metadata, redaction posture, and agent usage guidance.
• Buzz Bridge Operations: signed kind-9 intake, tenant mappings, queue evidence, safe retry, and current runtime capability limits.
• Workflows: workflow builder, node configuration, scheduling, credentials, templates, and endpoints.
• Chat & Agents: conversations with visible route economics, save-as-agent, and scheduled single-task agents.
• Chorus: model: "punk/chorus" governed intelligence route, request controls, evidence receipts, SDK helpers, and governance posture.
• Pantasso Integration: how Punk and Pantasso stay separate while Punk governs Pantasso agent runtime calls.
• Governance: policies, trust tiers, side-effect levels, approvals, observe mode, and audit.
• Governance Examples: concrete policy snippets and expected outcomes for support, CRM, web, side-effect, and observe-mode scenarios.
• Accounts & Orgs: user accounts, multi-org switcher, invitations, public signup, and email configuration.
• Usage & billing: plans, quotas, per-tenant usage metering, the usage API, and optional Stripe setup.
• Troubleshooting: common setup, routing, provider, workflow, governance, and billing symptoms.
• What's New: user-facing release notes.

What Customers Can Do

• Route OpenAI-compatible traffic through /v1/chat/completions.
• Route Anthropic-compatible traffic through /v1/messages.
• Route OpenRouter provider/model slugs through Punk's OpenAI-compatible gateway.
• Use existing OpenAI SDK, Vercel AI SDK, LangChain, Anthropic SDK, and Claude Code clients with Punk's gateway.
• Add @punktechnologies/sdk for tool tracing, side-effect declarations, feedback, SOM fetches, and evidence reads.
• Scaffold a runnable starter with npm create @punktechnologies/punk-agent@latest.
• Use Chorus with model: "punk/chorus" for governed, receipt-backed work.
• Build workflows in the dashboard, run them on demand, or schedule them by cron.
• Install 51 managed SaaS connectors for governed collaboration, engineering, CRM, support, billing, incident, observability, identity, data, compliance, communications, cloud, database, ERP, HR, recruiting, legal, revenue, scheduling, edge, infrastructure-as-code, and customer-data tools.
• Turn a useful chat into a reusable agent.
• Add identity headers so cost, policy, and audit records stay attributable.
• Configure policies, approvals, redaction, tripwires, and tenant settings.
• Invite teammates, manage organizations, issue tenant API keys, and review usage.
• Track cost, savings, blocked actions, and route explanations from the dashboard and API.
• Run enterprise pilots in an observe-first sequence before shadow, canary, proof review, and expansion.

Public Documentation Policy

Keep these pages focused on hosted setup, integration, tenant operation, security review, billing, troubleshooting, and customer-visible behavior. Do not add customer self-hosting or independent-infrastructure instructions to the public docs.