Getting Started
Kopai Cloud
Kopai Cloud is the hosted backend. Your app sends telemetry to a managed endpoint and your whole team reads it in one dashboard at app.kopai.app. It is free while in alpha, no credit card.
Prerequisites
Section titled “Prerequisites”- An application instrumented with OpenTelemetry. The Quickstart is the fastest way: your agent sets it up and tests it locally first. Manual Setup covers hand-wiring.
Step 1: Create an Account
Section titled “Step 1: Create an Account”Sign up at app.kopai.app/signup. You sign in with a magic link sent to your email.
Step 2: Generate a Backend Token
Section titled “Step 2: Generate a Backend Token”Your app authenticates to Kopai Cloud with a backend token. Creating tokens requires the owner or admin role.
- Open Settings → Access Tokens in the dashboard
- Click Generate Token and choose Backend Token
- Copy the token. It is shown once.
Building a browser app? Use a Frontend Token with allowed origins instead. The browser guide covers that setup.
Step 3: Point Your App at Kopai Cloud
Section titled “Step 3: Point Your App at Kopai Cloud”Set two environment variables for your instrumented app:
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-http.kopai.app"export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_BACKEND_TOKEN"Your instrumentation stays identical to local. Only the endpoint and the auth header change.
Step 4: Verify Ingestion
Section titled “Step 4: Verify Ingestion”Open app.kopai.app/observability and confirm traces, logs, and metrics are arriving from your app.
Step 5: Invite Your Team
Section titled “Step 5: Invite Your Team”- Go to Team in the dashboard
- Click Invite Member
Invited members get the member role. They can read all telemetry. Creating tokens stays with owners and admins.
Step 6: Authenticate the CLI
Section titled “Step 6: Authenticate the CLI”The CLI queries Kopai Cloud with its own read-only token. An owner or admin creates it:
- Open Settings → Access Tokens
- Click Generate Token and choose CLI Token
- Copy the token
Then log in:
npx @kopai/cli loginpnpm dlx @kopai/cli loginyarn dlx @kopai/cli loginPaste the token at the prompt. The CLI saves it to ./.kopairc with the server URL https://api.kopai.app/v2. See CLI authentication for flags, expiry, and logout.