KyroDB docs

Runtime credentials

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

KyroDB runtime credentials are backend environment values for a specific managed runtime. They are generated during runtime setup and are used by your API routes, workers, or agent services to call retrieval, change events, observability, and proof workflows.

Browser and mobile clients call your application backend. Your backend loads the KyroDB environment values and calls the runtime.

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 Issue 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' \
  --connect-timeout 5 \
  --max-time 20 \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/plain' \
  -H 'X-KyroDB-Bootstrap-Client: kyrodb-env-command/v1' \
  --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
if [ -f .gitignore ]; then
  grep -qxF '.env.kyrodb' .gitignore || printf '\n.env.kyrodb\n' >> .gitignore
else
  printf '.env.kyrodb\n' > .gitignore
fi
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, adds .env.kyrodb to .gitignore, removes the request file after success, and replaces .env.kyrodb only after success. The console shows only the bootstrap code and exchange endpoint; the terminal receives .env.kyrodb for backend processes.

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 managed secrets configuration instead of shipping the file.

Use the generated Runtime page smoke test before wiring production traffic. It uses tenant_id="demo", namespace="default", and a synthetic vector to verify connectivity, auth, embedding dimension, and trace output. Replace those demo values with your application scope and embedding pipeline in backend code.

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.	Use from trusted backend jobs, internal tools, or the KyroDB console.
`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 { randomUUID } from "node:crypto";
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") ?? 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 your managed secrets system.
Keep runtime credentials out of browsers, mobile apps, analytics tools, logs, and 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