Getting Started
Quickstart
Kopai is built for coding agents. You install the skills. Your agent does the rest. Everything runs locally without an account.
Prefer to wire things by hand? Follow Manual Setup. No app to instrument yet? Run the demo app instead.
Prerequisites
Section titled “Prerequisites”- Node.js v22.13.0+ installed
Quick Prompt
Section titled “Quick Prompt”Paste this into your coding agent and it handles Steps 1 and 2 for you:
Read https://kopai.app/quickstart.md and set up Kopai in my project.When it finishes, pick up at Step 3.
Step 1: Install the Kopai Skills
Section titled “Step 1: Install the Kopai Skills”npx skills add kopai-app/kopai-monopnpm dlx skills add kopai-app/kopai-monoyarn dlx skills add kopai-app/kopai-monoThe installer asks which skills to add. Select all three:
otel-instrumentation— instruments your app and proves telemetry arrivesroot-cause-analysis— investigates issues by querying your telemetrycreate-dashboard— builds dashboards from your metrics, logs, and traces
Coding agents running this command skip the picker and install all three automatically. The skills work with Claude Code and 20+ other agents. See AI Agent Skills for details and other install options.
Step 2: Ask Your Agent to Instrument
Section titled “Step 2: Ask Your Agent to Instrument”Add observability to my app and confirm telemetry reaches Kopai.The otel-instrumentation skill runs the whole loop: it starts the local Kopai backend, installs the OpenTelemetry SDK, instruments your code, drives traffic through the app, and asserts on the telemetry that arrives. It covers Node.js, Next.js, Python, Go, Java, .NET, Ruby, PHP, Rust, Erlang, and C++. Browser JavaScript needs Manual Setup.
Step 3: Ask Questions
Section titled “Step 3: Ask Questions”Ask these in a fresh chat. Instrumentation fills the agent’s context, and a new conversation gives better answers. One check first: the skill started Kopai inside the old chat, so if you closed that chat, the server is likely down. Ask your agent to start Kopai again, or run npx @kopai/app start yourself.
The validation run already produced telemetry: the skill hit every entry point and drove one failure on purpose. Ask about it:
Find the request that failed during validation and explain what happened.Then use your app and ask about the real traffic:
What are the slowest requests, and where do they spend their time?The root-cause-analysis skill answers by querying your telemetry through the Kopai SDK and CLI, and backs every finding with evidence. The dashboard at http://localhost:8000 shows the same data if you want to browse it yourself.
Next Steps
Section titled “Next Steps”Your telemetry is flowing. Pick what comes next: