Skip to main content

Building Your First App Kernel

This tutorial stands up a working Kilimanjaro project end-to-end: initialise the SDK, define a collection schema, configure anon access, and read records from a client app. No backend server, no manual auth plumbing.

The code examples below show the TypeScript SDK; the same operations are available in all twelve supported SDK languages — see the per-language SDK reference for the idiomatic translation.

Prerequisites​

Step 1 — Create a project​

In the Console, create a new project. Choose:

  • Jurisdiction — pick whichever is closest to your users (or whichever your compliance regime requires)
  • Custody mode — Platform-Managed (you can climb the ladder later without code changes)

The Console creates the project and mints a default API key. Copy the key once — it is shown only at creation.

Step 2 — Install the SDK​

See the Quickstart install table for the per-language install command across all twelve SDKs (TypeScript, Python, Go, Rust, Java, .NET, PHP, Ruby, Swift, Kotlin, Flutter, React Native).

Step 3 — Initialise​

Create your app entry-point and initialise the client. Per the Quickstart canonical pattern:

import { createClient } from '@k9o/core';

const k9o = createClient({
orgSlug: 'your-org',
projectSlug: 'your-project',
apiKey: process.env.K9O_API_KEY!,
});

The SDK opens a connection to the project's gateway and caches the JWKS for offline JWT verification. No further configuration is required for anon access.

Equivalent initialisation in the other eleven SDK languages follows the same shape — pass an API key from the environment, get a client back. See the per-language SDK reference for idiomatic translations.

Step 4 — Define a schema​

In the Console, navigate to Data → Schemas → New collection. Define a simple posts collection:

FieldTypeConstraint
idstringprimary key (auto-generated post_<base62>)
titlestringrequired, max 200
bodystringrequired
published_attimestampoptional

Save. The schema is created with default policy: read-only for anon callers, full access for authenticated users with the editor role.

Step 5 — Insert a starter record​

In the Console, navigate to Data → posts → New record. Fill in:

  • title: Welcome
  • body: First post on the platform
  • published_at: today's date

Save. The Console writes the row through the same gateway, policy, and audit path your app's SDK calls will use — there is no privileged backdoor.

Step 6 — Read from your app​

Back in your app entry-point, fetch and print the rows. The data-pillar SDK shape is documented in API → Data; the canonical fluent chain is:

const { data: posts } = await k9o.from('posts').select().limit(10);

for (const post of posts) {
console.log(post.title, '—', post.published_at);
}
// Output (illustrative):
// Hello world — 2026-10-27T09:00:00Z

Run your app per the runtime conventions of your chosen language (npx tsx app.ts, python app.py, go run ., cargo run, etc.). You should see your Welcome row printed. The query went through Gate (anon-authenticated), through the four-pillar policy evaluation (anon role passes the default read rule), through RLS (no row filter at this stage), and back to your client.

rows returned to the clientClient appSDK select()limit(10)Gateanon-authenticatedPolicyfour-pillarread rule passesRLSno row filterpostscollectionAudit event data.posts.selectsubject.type anon, same requestId
The select call passes Gate, policy evaluation and row-level security before it reaches the data, and every call leaves an audit event.

Step 7 — Confirm in the audit log​

Open Audit → Recent events in the Console. You should see:

  • A data.posts.select event with subject.type: "anon" and your originating IP
  • The full requestId correlation key that ties this event to your client call

Every operation produced a forensic record — no extra code, no separate observability stack.

What just happened​

In about five minutes, you have:

  1. A project with a defined data residency (the jurisdiction you chose)
  2. A schema with platform-enforced types and a default policy
  3. An anon-callable read surface, MFA-gated for any future write surfaces
  4. A tamper-evident, signed audit trail for every call

The same code path that powered the select above will, with one custody-mode change in the Console, run against BYOK or HYOK key custody — without changing the application code. That is the substitution-free path the platform's custody ladder is designed for.

Next​