APIs, integrations & migration

Connection bundle and doctor

Gives a developer the exact URLs, environment variable names and starter snippets for a project, and a read-only check that a client can really connect.

Available in previewEngine edition 5f8ea3af

What it does

An administrator can fetch a secret-safe connection bundle for a project, and the kynetra command-line tool can print it as environment variables or JSON and run a staged connection check. The check stops at the first failing stage and reports a stable code. It needs an authorized read to succeed, so a reachable server is not mistaken for a working connection.

How it works

GET /admin/v1/projects/{id}/connect returns kynetra.connect/v1: the base URL, the project name and status, the project publishable key, whether a service key is configured (never its value, which cannot be shown again and has to be rotated to get a new one), browser and server environment variable names with example values, at least eleven generated snippets for common runtimes, SDK metadata and a note on browser origins. The caller must be a platform super administrator or an owner or administrator of that project. Any other caller, including one holding a token from a different project, gets a 403 before the existence of the project is disclosed.

The base URL comes from the KYNETRA_PUBLIC_URL setting when it is valid: an HTTPS origin with no path or credentials, or an HTTP origin on a loopback host. Forwarded-host headers are not trusted to set it, so a caller cannot make the bundle print a different origin.

kynetra connect --remote <url> --project <id> prints a summary, environment variables or JSON. --runtime chooses the public variable prefix for nextjs, vite, astro, sveltekit, nuxt, node or cloudflare. With --check it runs the same diagnosis as kynetra doctor.

The doctor stages run in order: URL parse, DNS and reachability, TLS, health, readiness, discovery schema, API compatibility, authentication, project status and an authorized minimal read. The first hard failure stops the chain with its code. Output is text or JSON with secrets redacted, and the exit status is zero when every stage succeeds and non-zero otherwise.

The admin console also serves a static connect panel (options, an agent prompt and the HTTP equivalents of a connection string). KynetraDB does not speak the PostgreSQL wire protocol, so the connection string route returns the base URL, health URLs and the login and first-call examples.

Where you reach it

  • HTTPGET /admin/v1/projects/{id}/connect
  • CLIkynetra connect --remote <url> --project <id> [--format summary|env|json] [--runtime nextjs|vite|astro|sveltekit|nuxt|node|cloudflare] [--check]
  • CLIkynetra doctor --remote <url> [--project <id>] [--json]
  • HTTPGET /admin/connect/options, /admin/connect/agent-prompt, /admin/connect/connection-string

Example

Check a connection end to end, then print the environment for a Next.js appbash
kynetra doctor --remote https://db.example.com --project PROJECT_ID
kynetra connect --remote https://db.example.com --project PROJECT_ID --format env --runtime nextjs

Limits

  • The service key is never shown in the bundle. A project that needs a new one has to rotate it.
  • The generated snippets are starting points for HTTP clients. The TypeScript client package is described by the server as source available and unpublished.
  • kynetra doctor tests one base URL at a time and cannot see a proxy or firewall rule that treats other routes differently.

Evidence

  • On this siteDocumentation hub
  • TestsCovered in the engine repository by 9 connection-contract tests (the bundle carries no service key or secret, authorization boundaries, forged project tokens, spoofed forwarding headers, canonical snippets, discovery) and 3 doctor tests

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to try this against your own workload.