Sealed checkpoint format

A sealed checkpoint is a directory laid out like the original Hugging Face checkpoint, with the original architecture and tensor names, so that stock SGLang or vLLM loads it with its own model classes. Two things are added: seal metadata that records the scheme, the transform and the key fingerprint, and an encrypted file, trusted.kllm, that holds what must stay secret, chiefly the permuted tokenizer. Unless the model was sealed with --no-lock, the weight shards are also locked: encrypted in place, with the same layout. This page specifies these parts, for decoder LLMs and for the diffusion pipeline variants.

This page describes the format written by kLLM 0.1.0.dev0.

How kLLM recognizes a sealed directory

kLLM reads the seal metadata from kllm.json at the top of the directory when that file exists (diffusion pipelines), and otherwise from the kllm object in config.json (decoder LLMs). A directory with neither is not sealed. The scheme field selects the code path:

`scheme`	Metadata file	Used for
`l1`	`config.json`	Decoder LLMs (Qwen3, Qwen3-MoE, Qwen2/2.5, Llama 3.x, FP8 variants).
`l1`	`kllm.json`	MiniMax H3 pipelines (`architecture` is `MiniMaxH3`).
`client`	`kllm.json`	Z-Image pipelines sealed with `kllm seal --client`.
`d1-v1`	`kllm.json`	Z-Image pipelines sealed without `--client`; used only by `kllm demo`.

kllm serve --key compares the recorded fingerprint with the unlocked key before it decrypts anything, and refuses a directory sealed under another key.

Decoder LLMs

Qwen3-8B-sealed/
  config.json                          base config plus the "kllm" object
  model-00001-of-0000N.safetensors     sealed weights, locked by default
  ...
  model.safetensors.index.json         weight map
  trusted.kllm                         encrypted permuted tokenizer
  generation_config.json, tokenizer_config.json, merges.txt, ...   copied unchanged

config.json

The original configuration with architectures unchanged, tie_word_embeddings set to false, and a kllm object with the following fields:

Field	Content
`scheme`	`"l1"`.
`transform`	`"orth"` or `"perm"`.
`fingerprint`	Key fingerprint, 64 bits of HKDF-SHA256 output written as four groups of four hexadecimal digits (for example `3f9a-0c41-d27e-88b5`). It identifies the key and reveals nothing about it.
`base_architecture`	The architecture that was sealed, for example `Qwen3ForCausalLM`.
`vocab_regular`	Number of regular token ids. The vocabulary permutation acts on these ids; special tokens keep their ids.

model-NNNNN-of-NNNNN.safetensors

The transformed weights, written in shards of about 4 GiB with safetensors metadata {"format": "pt"}. Tensor names and shapes are those of the original, with two exceptions: lm_head.weight is always written, because tied embeddings are untied; and in MoE models each expert’s tensors move to another expert index. FP8 checkpoints keep their weight_scale_inv or weight_scale tensors next to each weight.

model.safetensors.index.json

{"metadata": {}, "weight_map": {...}}, mapping every tensor to its shard.

Other files

Every other top-level file of the source directory is copied unchanged, except tokenizer.json and vocab.json, which exist only inside trusted.kllm, and tokenizer.model and spiece.model, which are left out because they list the vocabulary in canonical order. Weight files in .bin, .pt or .pth format are not copied.

The `trusted.kllm` blob

trusted.kllm is a chunked AES-256-GCM container. All integers are little-endian.

Field	Size	Content
Magic	10 bytes	`KLLMBLOB1` followed by a newline (`0x0a`).
Header length	4 bytes	Unsigned 32-bit length of the header.
Header	variable	JSON with sorted keys: `chunk` (plaintext chunk size, 64 MiB), `chunks` (number of chunks, at least 1), `fingerprint` (key fingerprint), `salt` (16 random bytes, hexadecimal).
Chunks	`chunks` times	Each chunk is the AES-256-GCM ciphertext of up to 64 MiB of payload followed by its 16-byte tag. No data may follow the last chunk.

Encryption of each chunk:

Key: HKDF-SHA256 of the 32-byte model key, with salt kllm/v1 and info l1/trusted-blob/<salt in hexadecimal>, 32 bytes. A fresh salt is drawn on every seal.
Nonce: 12 bytes, four zero bytes followed by the chunk index as an unsigned 64-bit integer.
Associated data: the header bytes, followed by the chunk index as an unsigned 64-bit integer and a one-byte flag that is 1 for the last chunk and 0 otherwise.

Because the header, the index and the last-chunk flag are authenticated, chunks cannot be reordered, dropped or truncated, and the header cannot be altered, without the authentication check failing. A reader rejects a wrong magic, a fingerprint that does not match the key, a failed authentication tag and trailing data.

The decrypted payload is a safetensors archive. Each secret file is stored as a uint8 tensor named file/<path>, for example file/tokenizer.json; trusted tensors, where a scheme has them, are stored under their own names.

MiniMax H3 pipelines

A sealed H3 partition keeps the diffusers layout of the original (model_index.json, text_encoder/, transformer/, video_vae/, audio_vae/, tokenizer/, processor/, schedulers and configs), with the same file names and tensor names:

text_encoder/ and transformer/ shards hold the sealed weights.
video_vae/ and audio_vae/ hold permuted latent interfaces, and the per-channel latent statistics (latents_mean, latents_std) in their configuration files are permuted accordingly.
tokenizer.json and vocab.json of tokenizer/, processor/ and text_encoder/ are removed and stored in trusted.kllm at the top of the directory (as file/tokenizer/tokenizer.json and so on).
kllm.json holds scheme ("l1"), transform, fingerprint, architecture ("MiniMaxH3"), partition (from model_index.json) and vocab_regular.

Z-Image pipelines

A Z-Image pipeline sealed with --client keeps the diffusers layout:

text_encoder/ and transformer/ shards hold the sealed weights; in transformer/ only the patch embedder, the final layer and the caption embedder differ from the original.
tokenizer/tokenizer.json and tokenizer/vocab.json are removed and stored in trusted.kllm at the top of the directory.
vae/, the scheduler and the configuration files are copied unchanged. Image files (.jpg, .png) and teaser.* files are not copied.
kllm.json holds scheme ("client"), transform, fingerprint, architecture ("ZImagePipeline"), vocab_regular and latent_channels.

The cloud’s part written by --client is a subset of this directory without trusted.kllm, tokenizer files, chat templates and vae/; see Client-keyed mode.

A Z-Image pipeline sealed without --client (scheme d1-v1) holds transformer/untrusted.safetensors, transformer/trusted.kllm (trusted tensors in the payload) and a kllm.json with scheme, fingerprint and architecture. Only kllm demo serves it.

Locked weights

A locked directory carries a lock flag in its seal metadata: "lock": "v1" in the kllm object of config.json (decoder LLMs) or in kllm.json (pipelines). Each locked safetensors shard records, in its header metadata under kllm.lock, a JSON object that maps each locked tensor’s name to its domain size, which encodes the tensor’s largest binary exponent. Only safetensors shards outside the tokenizer/, processor/ and vae/ directories are locked, and within them only tensors in bf16, fp16, fp32 or an FP8 format. The key stream of a tensor is derived from the model key and the tensor’s name, scoped by its component directory, so that resharding a model keeps the names.

An unlocked copy written by kllm serve --key, kllm unlock or kllm cloud has the same layout, without the flag and without the header entries. A lock version that this kLLM does not read is refused when unlocking.

What the format protects

Only trusted.kllm is encrypted and authenticated. Locked weight shards are encrypted (Locked weights) but not authenticated. The index, the configuration files and the seal metadata are plain files. None of them is signed, and kLLM does not detect their modification. Protect their integrity with the storage and distribution channel until signing is available; for a catalog model, kllm-manifest.json lists the digest of every file, and kllm verify rebuilds the model from its public base (Checking a published model).

Compatibility

The sealed weights keep the architecture, tensor names and shapes of the original, so the engine loads them with its own model class and kernels. kLLM supplies the decrypted tokenizer separately (--tokenizer-path for SGLang, --tokenizer for vLLM, a view of the pipeline directory for H3).
The format version is carried by the blob magic KLLMBLOB1, the scheme names and the HKDF salt kllm/v1. 0.1.0.dev0 is a development pre-release, and no format compatibility is guaranteed between pre-releases. If kllm serve refuses a sealed directory after an upgrade, seal the original checkpoint again. See Versioning and format stability.
The transforms are derived from the key, but the blob salt is random, so two seals of the same checkpoint under the same key produce different trusted.kllm files.

Planned

Note

Part of the upcoming 0.2 line. A store record per model in the local store, with the SHA-256 digest of every file and the sealing metadata, and the kllm show and kllm check commands (Store record and manifests). Records and catalog manifests hold digests, not signatures; artifact signing is planned. See Roadmap.