Developer Docs•stable•Updated 2026-07-06

Local Development

Test Kadryn integrations locally without leaking secrets or polluting production cost data.

Local development should validate your integration without exposing secrets or polluting production data.

Use local or test environments, synthetic traffic and safe prompts.

Environment variables

Use a local .env file that is ignored by Git.

bash
KADRYN_API_KEY="kadryn_test_..."
KADRYN_API_BASE_URL="https://api.kadryn.com/v1"
KADRYN_GATEWAY_BASE_URL="https://gateway.kadryn.com/v1"
KADRYN_ENVIRONMENT="local"

Do not use production keys in local development unless there is no alternative and the risk is understood.

Metadata for local traffic

Always mark local traffic clearly:

txt
X-Kadryn-Environment: local
X-Kadryn-Project: local-dev
X-Kadryn-Feature: integration-test

This keeps local tests separate from production costs and alerts.

Safe test prompt

Use non-sensitive prompts.

txt
Hello from local Kadryn integration test.

Do not send customer data, secrets, provider keys or production prompts while testing.

Gateway local test

bash
curl "$KADRYN_GATEWAY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Kadryn-Project: local-dev" \
  -H "X-Kadryn-Feature: integration-test" \
  -H "X-Kadryn-Environment: local" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "Hello from local development"
      }
    ]
  }'

Direct ingest local test

bash
curl "$KADRYN_API_BASE_URL/usage/events" \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-usage-test-001" \
  -d '{
    "timestamp": "2026-07-06T12:00:00.000Z",
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "inputTokens": 10,
    "outputTokens": 5,
    "costCents": "1",
    "project": "local-dev",
    "feature": "integration-test",
    "environment": "local"
  }'

Verify locally

Open:

txt
Developers → Logs & Traces

Filter by:

  • environment local;
  • project local-dev;
  • synthetic traffic;
  • trace ID;
  • request group ID.

Avoid production pollution

Do not let local traffic trigger:

  • production caps;
  • production alerts;
  • finance reports;
  • executive dashboards;
  • customer unit economics.

Use environment filters and test projects.

Troubleshooting

Local request does not appear

Check API key, base URL, environment filters and whether the request failed before reaching Kadryn.

Local request appears as production

Fix X-Kadryn-Environment or direct ingest environment.

Secret accidentally committed

Rotate the key immediately and remove it from Git history if needed.

Related pages