kolm  /  learn  /  first .kolm in 5 minutes

First .kolm in 5 minutes.

By the end of this page you will have one signed .kolm file on your laptop. It redacts PII from any text you throw at it. It runs offline. No data leaves your machine.

Golden Path 1 of 3 . v1.0 . tested on macOS, Linux, Windows (PowerShell + cmd)

Before you start

You need Node.js 20 or newer and a terminal. That is the whole list. The CLI is one self-contained JavaScript binary; no Docker, no Python, no GPU. kolm compile in cloud mode pings kolm.ai for the build step, but every command on this page works offline once the artifact is on disk.

node --version  # should print v20.x or higher

kolm ships from GitHub. One npm command, then it is on your PATH as kolm.

npm i -g github:sneaky-hippo/kolmogorov-stack

kolm --version

kolm v0.2.6

kolm build is the one-shot wrapper. It scaffolds a spec, generates a small seed set, compiles the artifact, verifies the signature chain, and prints the K-score. --from redactor picks the PII redactor template; --yes accepts every default.

kolm build my-redactor --from redactor --yes

scaffolding spec my-redactor.spec.json (template: redactor) . ok
generating seeds my-redactor.seeds.jsonl (10 rows) . ok
compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
K-score for my-redactor.kolm: 0.874  (gate >= 0.85 - pass)
verifying signature . ok
artifact written: my-redactor.kolm  (28.4 KB)

try it:
  kolm run my-redactor.kolm --input <sample.json>
  echo {"text":"..."} | kolm run my-redactor.kolm

kolm inspect prints the manifest in plain text. This is what a security reviewer sees when they audit the artifact.

kolm inspect my-redactor.kolm

artifact: my-redactor.kolm
task:     redact identifier patterns from free text
built:    2026-05-16 14:22:08Z (12s ago)
size:     28.4 KB on disk

K-score for my-redactor.kolm: 0.874  (gate >= 0.85 - pass)

runtime:    cloud
tier:       starter
base model: none (recipe-only)
signature:  valid (hmac-sha256)
recipes:    1 (redact-identifiers-v1)
evals:      10 cases

kolm run executes the artifact against an input. JSON in, JSON out. The execution is local; no network call.

echo {"text":"patient John Doe, SSN 123-45-6789, email j.doe@hospital.org"} | kolm run my-redactor.kolm

patient [REDACTED_NAME], SSN [REDACTED_SSN], email [REDACTED_EMAIL]

recipe: redact-identifiers-v1  .  3.2 ms

Or with a file input (works on Windows cmd too, no quoting headaches):

echo {"text":"call me at 415-555-2244"} > sample.json
kolm run my-redactor.kolm --input sample.json

call me at [REDACTED_PHONE]

recipe: redact-identifiers-v1  .  2.8 ms

The .kolm file is a zip with deterministic contents. kolm eject unpacks it. Nothing is hidden; nothing is encrypted. This is the "no lock-in" promise made into a verb.

kolm eject my-redactor.kolm

ejected my-redactor.kolm -> ./my-redactor.eject
  9 files, sha256=a1b2c3d4e5f6...

no lock-in. your AI is yours.
  cat ./my-redactor.eject/EJECT_README.md   # what each file is
  cat ./my-redactor.eject/manifest.json     # task, base, K-score
  kolm inspect my-redactor.kolm              # re-verify the signature chain

Inside the ejected folder:

• manifest.json task, base model, signing mode, K-score, content hashes
• spec.json the spec you compiled from, verbatim
• recipes/ deterministic JS routines kolm chose to satisfy the spec
• evals.jsonl the (input, expected) cases that produced the K-score
• receipts/ HMAC chain receipts proving the compile pipeline ran end-to-end
• signature.json detached signature over manifest + recipes + evals
• EJECT_README.md plain-English guide to every file, auto-generated

What just happened

You compiled a spec into a deterministic AI artifact and ran it on your hardware. The artifact has a measurable accuracy score (K), a cryptographic signature, and a fully auditable bill of materials. No vendor lock-in: the file is a standard zip, the recipe inside is plain JavaScript, and the algorithm that scored it is open-source. The whole thing is 28 KB.

This is the minimum viable kolm. Everything else in the product (cloud GPU training, team-private hub, edge export to phones, RAG attachment, agent observation loops) is built on top of this one shape.

What to do next

If something went wrong

• npm error: Node version mismatch. node --version must be 20.0.0 or higher.
• K-score below 0.85: the iterate guidance prints next steps. Most common fix: kolm seeds validate my-redactor.seeds.jsonl to check the seed set, then re-run kolm build.
• Windows cmd quoting: single quotes around JSON do not work in cmd.exe. Use --input <file> or pipe via echo as shown above.
• kolm: command not found: npm config get prefix should be on your PATH. Or run npx -y github:sneaky-hippo/kolmogorov-stack build my-redactor --from redactor --yes.
• Still stuck: open an issue at github.com/sneaky-hippo/kolmogorov-stack/issues or email hello@kolm.ai.