# Safetensors

This page draws on the public safetensors format specification, not on a decided Tensormorph-specific design document - treat implementation details (exact field names, APIs) as illustrative of the *approach*, not a frozen interface.

Safetensors is the simplest checkpoint format Tensormorph opens, and it's a useful baseline for understanding why the format matters more to Tensormorph than it might to a training script: the format itself is what makes near-instant remote inspection possible.

## Why the format matters for inspection

A safetensors file is three parts, in order:

1.  An 8-byte little-endian integer giving the length of the header.
2.  A JSON header listing every tensor's name, dtype, shape, and byte-offset range within the data section - nothing else.
3.  A raw, contiguous data section: every tensor's bytes back-to-back, no pickling, no arbitrary code.

Because the header is a small, fixed-offset JSON block, Tensormorph can fetch *just the header* - a single small HTTP range request against a remote checkpoint - and know the full tensor tree (every name, shape, and dtype) before downloading a single byte of weight data. This is what makes opening a multi-hundred-gigabyte remote checkpoint feel instant in the Outliner: the tree populates from the header alone, and each tensor's data loads lazily, only when something actually needs it (a view comes on-screen, a query touches it, a probe reads a scalar).

This "fetch the header, defer the data" pattern is the baseline every format Tensormorph supports is held to, not a safetensors-specific special case. A format that requires reading the whole file to know what's inside it is a worse fit for Tensormorph's streaming model, and gets flagged as such in its importer.

## No arbitrary code execution

Unlike Python's `pickle` (used by legacy `.bin`/`.pt` checkpoints), safetensors carries no executable payload - loading one cannot run attacker-controlled code. This matters directly for Tensormorph, since one of its stated jobs is opening third-party checkpoints of unknown provenance; a format that can't execute code on load is a meaningfully smaller attack surface for that workflow than one that can.

## Zero-copy, slice-addressable loading

Because every tensor occupies a known, contiguous byte range, Tensormorph can map a tensor - or a *slice* of one - directly from the underlying storage (disk, memory-mapped file, or a range-fetched remote buffer) without an intermediate deserialization pass. This is the same zero-copy principle behind Tensormorph's own tile-streaming engine: a 2D Matrix/Heatmap view showing one tile of a 100,000×100,000 weight matrix only ever touches the bytes for that tile, whether the source is a local safetensors file or a remote one.

## Metadata

Safetensors reserves an optional `__metadata__` key in the header for free-form string key-value pairs (framework, quantization scheme, training run ID, and so on). Tensormorph reads this into a tensor's provenance fields where present, but - because the field is optional and unstructured - never depends on it being there; shape, dtype, and byte offsets are the only fields guaranteed by the format itself.

## Related resources

-   [Shape, Rank, Stride and Layout](/docs/core-concepts/shape-rank-stride-layout) - safetensors tensors are dense and contiguous; Tensormorph's own tensor model additionally tracks stride and view relationships once a tensor is loaded.
-   [Level of Detail and Streaming](/docs/core-concepts/level-of-detail-and-streaming) - how partial, lazy loading extends beyond the header to tile-level data.
-   [Sharded Checkpoints](/docs/working-with-models/sharded-checkpoints) - for checkpoints split across many safetensors files with an index.