KyroDB docs

Runtime credentials

Find, copy, and store the server-side runtime environment values safely.

KyroDB runtime credentials are server-side bearer tokens for a specific managed runtime. They are generated during runtime setup and are used by your backend to call retrieval, change events, observability, and proof workflows.

Do not put these values in browser code. Do not prefix them with NEXT_PUBLIC_.

Where to get them

Open console.kyrodb.com.
Select your project.
Go to Runtime.
Wait until the runtime has a ready endpoint.
Open Backend environment.
Click Create env command.
Run the generated terminal command from your backend, worker, or agent service.

(
set -e
tmp="$(mktemp .env.kyrodb.XXXXXX)"
request="$(mktemp .kyrodb-bootstrap.XXXXXX)"
trap 'rm -f "$tmp" "$request"' EXIT
chmod 600 "$tmp" "$request"
printf '%s' '{"code":"kyrb_one_time_code"}' > "$request"
if ! http_status="$(curl -sS -o "$tmp" -w '%{http_code}' -X POST 'https://console.kyrodb.com/api/runtime/bootstrap/exchange' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/plain' \
  --data-binary "@$request")"; then
  printf 'KyroDB bootstrap exchange failed before receiving a response.\n' >&2
  exit 1
fi
case "$http_status" in
  2??) ;;
  *)
    printf "KyroDB bootstrap exchange failed (HTTP $http_status):\n" >&2
    cat "$tmp" >&2
    exit 1
    ;;
esac
mv "$tmp" .env.kyrodb
rm -f "$request"
trap - EXIT
)

The generated command uses a short-lived, one-time bootstrap code, writes the exchange request and credentials through private temporary files, cleans up on failure, removes the request file after success, and replaces .env.kyrodb only after success. The browser sees the code and endpoint only; runtime bearer tokens are returned to the terminal response and should be loaded only by backend code.

A ready endpoint means the Runtime page has confirmed healthy or degraded runtime health. Degraded runtimes are callable, but review the health summary before depending on them for production traffic.

Load .env.kyrodb into your backend process before using SDK env helpers. For local Node development:

node --env-file=.env.kyrodb server.mjs

SDKs read environment variables from the process, not from .env.kyrodb directly. In deployed environments, copy these values into your server, worker, or secret-manager configuration instead of shipping the file.

What each value does

Variable	Required for	Notes
`KYRODB_BASE_URL`	All SDK and HTTP calls.	The runtime endpoint origin shown in the Runtime page.
`KYRODB_DATA_PLANE_TOKEN`	Retrieval, change events, invalidation, feedback, and certified mutations.	Use only from backend code that is allowed to serve or mutate context.
`KYRODB_OBSERVABILITY_TOKEN`	Trace lookup, diagnosis, proof reports, replay, shadow, and health workflows.	Keep behind a backend, CLI, or console BFF.
`KYRODB_EMBEDDING_DIMENSIONS`	Smoke tests and examples.	Non-secret managed-runtime metadata; your query embeddings must match this dimension.

The SDKs also support:

Variable	Use
`KYRODB_SHADOW_SESSION_ID`	Route serving calls through an isolated shadow session during replay/adoption testing.
`KYRODB_ALLOW_INSECURE_HTTP`	Local development only. Allows loopback or explicitly insecure HTTP clients when set by the SDK user.

Backend-only examples

Next.js Route Handler:

import { KyroDBClient } from "kyrodb";
 
export async function POST(request: Request) {
  const client = KyroDBClient.fromEnv();
  const body = await request.json() as { question?: unknown };
  const question = typeof body.question === "string" ? body.question.trim() : "";
 
  if (!question) {
    return Response.json({ error: "question is required" }, { status: 400 });
  }
 
  const tenantId = "acme"; // derive this from your authenticated application user
  const queryEmbedding = await embedUserQuestion(question); // from your embedding pipeline
 
  const packet = await client.retrieve({
    query_embedding: queryEmbedding,
    scope: { tenant_id: tenantId, namespace: "kb" },
    top_k: 8,
    freshness_mode: "strict",
    include_content: true
  }, {
    idempotencyKey: request.headers.get("x-request-id") ?? crypto.randomUUID()
  });
 
  return Response.json(packet);
}

Python worker:

from kyrodb import KyroDBClient
 
client = KyroDBClient.from_env()
question = "How do refunds work for annual plans?"
request_id = "worker-req-2026-05-01-001"
tenant_id = "acme"
embedding = embed_user_question(question)  # from your embedding pipeline
 
packet = client.retrieve(
    query_embedding=embedding,
    scope={"tenant_id": tenant_id, "namespace": "kb"},
    top_k=8,
    freshness_mode="strict",
    idempotency_key=request_id,
)

Security rules

Store runtime credentials in backend environment variables or a secret manager.
Never send runtime credentials to browsers, mobile apps, analytics tools, logs, or LLM prompts.
Use the data-plane token for agent retrieval and change events.
Use the observability token only in trusted operational paths.
Rotate or revoke credentials immediately if they are exposed.

Next guidePython SDK