Skip to main content
Documentation menu

Local JSON Package Index

Cabin resolves versioned dependencies against a tiny on-disk JSON index. This is not a real registry - it has no network protocol, no append-only structure, and no signing. The format carries resolver metadata plus, per version, one archive record per packaging revision, so cabin.lock can pin exact bytes and cabin fetch / cabin build can materialize registry packages.

For --index-path local file indexes, HTTP, OCI, Git, and remote source paths are not supported. The only source shape recognized there is type = "archive" / format = "zip" with a local filesystem path. Sparse HTTP indexes are documented below and use the same archive source records after URL resolution.

Index sources

cabin resolve / fetch / build / update reaches the package index through one of two flags. They are mutually exclusive - passing both fails with use either --index-path or --index-url, not both.

FlagBackendSection
--index-path <path>local filesystem directoryDirectory layouts
--index-url <url>sparse HTTPSparse HTTP index

Local-only projects (no versioned dependencies) require neither flag.

Directory layouts

--index-path <path> accepts two on-disk shapes:

Flat layout

index/
  fmt.json
  spdlog.json
  ...

Every file whose name ends in .json is treated as a package metadata file; other files (README.md, .gitignore, …) are ignored. Source paths in package metadata resolve relative to this directory.

Registry-root layout

registry/
  config.json
  packages/
    fmt.json
    spdlog.json
  archives/
    fmt/
      fmt-10.2.1-0123456789abcdef.zip
      fmt-10.2.1-9a93b2b7dfdac77c.zip
    spdlog/
      spdlog-1.13.0-9a93b2b7dfdac77c.zip

When a config.json is present at the index root the loader uses the registry-root layout: config.packages (default "packages") points at the directory holding <name>.json files, and source paths in those files resolve relative to that directory - i.e. "../archives/fmt/fmt-10.2.1-0123456789abcdef.zip" lands at registry/archives/fmt/fmt-10.2.1-0123456789abcdef.zip. The trailing segment of every archive filename is the packaging revision, so each revision of a version keeps its own file.

In both layouts a scoped package <scope>/<name> nests exactly one level deeper as <scope>/<name>.json (e.g. packages/fmtlib/fmt.json); its declared name must be the full <scope>/<name>, and its source paths resolve relative to the scope directory, matching the published "../../archives/<scope>/<name>/<scope>-<name>-<version>-<revision>.zip" form. Anything nested deeper than one scope directory is ignored.

In both layouts a source path must name a regular file inside the index root (the directory --index-path or [registry] index-path names), reached without a symlink: .. is resolved textually and may climb out of the packages or scope directory, never out of the root, no component may end in a space or a dot (which Windows would drop) or name a Windows device such as NUL, and an absolute path is read only when it spells a path inside it. Fetch refuses any other path with the error it gives a missing file (is not a file inside the registry root), so a source path cannot make fetch read, hash, or probe a file elsewhere. That covers source paths only: the loader reads config.json and the metadata files as it finds them, symlinks included.

config.json itself must satisfy schema = 2, kind = "file-registry", and reject .. or absolute paths in the configured subdirectories. Over the sparse HTTP index the subdirectories must additionally resolve, once joined onto the index URL, to the same origin as that URL, at or below its path, and with no userinfo - so a subdirectory cannot move metadata or archive fetches to another host; only dl names another host, and only for archives. A subdirectory containing %, \, ?, or # is rejected outright, because a URL parser and a filesystem path disagree about what those characters mean. See registry-design.md for the full layout contract.

Schema 1, which the Cabin 0.18.0 release and earlier read and wrote, named the archives field artifacts. Neither schema is read by the other’s clients, and the old field has no alias. A schema 1 file registry keeps working once its config.json says "schema": 2 and names the field archives: "archives": "artifacts" leaves the directory and every published source.path as they are.

config.json may also carry three optional fields belonging to the remote-registry protocol: auth-required (bool; every request to the registry except the always-public config.json itself must carry Authorization: Bearer <token>), api (string; absolute http(s) base URL of the registry web/API origin, rejecting non-http(s) schemes and userinfo credentials), and dl (string; absolute base URL of the host that serves the archives over HTTP, see Sparse HTTP index). Both index loaders - this local loader and the sparse HTTP client - recognize the fields unconditionally, so a vendored or mirrored copy of a hosted registry loads like any other file registry; the read routes never consult api (only the experimental mutation commands do), and this local loader reads archives from the directory whatever dl says. See remote-registry.md for the full protocol.

In both layouts the filename stem (fmt for fmt.json) must equal the package’s declared name field. Mismatches produce a clear error.

Package file shape

{
  "schema": 1,
  "name": "fmt",
  "versions": {
    "10.2.1": {
      "dependencies": {},
      "yanked": false,
      "revision": "9a93b2b7dfdac77c",
      "revisions": {
        "0123456789abcdef": {
          "checksum": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "published-at": "2026-01-14T09:12:33Z",
          "source": {
            "type": "archive",
            "path": "../archives/fmt/fmt-10.2.1-0123456789abcdef.zip",
            "format": "zip"
          }
        },
        "9a93b2b7dfdac77c": {
          "checksum": "sha256:9a93b2b7dfdac77c9a93b2b7dfdac77c9a93b2b7dfdac77c9a93b2b7dfdac77c",
          "published-at": "2026-02-02T18:40:07Z",
          "source": {
            "type": "archive",
            "path": "../archives/fmt/fmt-10.2.1-9a93b2b7dfdac77c.zip",
            "format": "zip"
          }
        }
      }
    }
  }
}
FieldRequiredDescription
schemayesSchema version: 1, or 2 when a revision carries its own resolution. Other values produce a clear error, and a reader that predates schema 2 refuses such a file rather than resolve a pinned revision with another revision’s metadata.
nameyesPackage name. Must equal the file’s stem.
versionsyesMap from SemVer version string to version metadata. May be empty. Keys are plain upstream versions; a key carrying SemVer build metadata (10.2.1+anything) is rejected.

Each version’s metadata:

FieldRequiredDefaultDescription
dependenciesno{}Map from package name to version requirement string. The same requirement subset as cabin.toml (see docs/manifest.md).
build-dependenciesno{}The version’s build dependencies, in the encoding of dependencies. They resolve with dependencies into one lockfile. A Cabin older than this field rejects a package document that carries it.
build-scriptnononeThe build script the version’s archive holds in its root: "build.c" or "build.cpp", and no other value. A build runs a registry package’s script only when this field declares it. A Cabin older than this field rejects a package document that carries it.
yankednofalseWhen true, the resolver excludes this version from candidate sets.
revisionnonullThe version’s current packaging revision: the one a fetch uses when no lockfile pins another. Must name a key of revisions.
revisionsno{}Every fetchable packaging revision of this version, keyed by revision id. See Packaging revisions.
featuresnoomittedDeclared [features], validated like a manifest’s table. Resolution selects a version for a feature request only when this table declares the feature; an entry that omits the field loads and declares only an empty default.
standardsnoomittedDeclared per-target language-standard table (interface requirements plus header-only / gnu-extensions flags). Absence, at any granularity, means unconstrained, so older entries that omit the field continue to load. See Standard metadata.
linksnoomittedDeclared per-target links claims, keyed by target name. Absence means the version claims nothing, so older entries that omit the field continue to load. See Links metadata.
upstreamnoomittedDeclared [package.upstream] provenance: url, the algorithm-prefixed upstream checksum (sha256:<hex>, distinct from a revision’s archive checksum), format, optional strip-prefix, optional patches list, optional copy steps. Loaded into the typed provenance model, whose validation rules match the manifest’s (manifest.md). Inert for resolution and fetching; older entries that omit the field continue to load.
licensenoomittedDeclared license SPDX expression of the current revision, as the publishing Cabin validated it. Metadata only: resolution and fetching never read it, and the index reader does not validate it, so an identifier newer than the reading Cabin’s SPDX lists still loads. Every publish declares one. An entry published before that was required still loads during the hosted registry’s private alpha; readers require the field before the public launch.

Unknown fields anywhere in the file are rejected.

Packaging revisions

The immutable unit of a registry is the triple (name, version, revision). A version is a plain upstream version and never changes meaning; a packaging revision is one set of archive bytes published under it, so a correction to how a version is packaged lands as a new revision rather than as a new version or as replaced bytes.

A revision id is the first 16 lowercase hex characters of the archive’s SHA-256 digest, which has two consequences the whole system leans on: republishing the identical archive maps onto the revision that already exists, and a revision id can always be re-derived from a sha256:<hex> checksum by taking its prefix. Resolution picks a version, and the lockfile’s checksum picks its revision.

A respin may change what resolution reads - dependencies, build-dependencies, build-script, features, standards, and links - because a revision’s archive and the graph resolved for it always agree. The version-level fields belong to the current revision; a revision whose resolution metadata differs carries its own in a resolution object (schema 2), so a lockfile that pins it keeps resolving exactly what its archive declares:

ModeRevision whose metadata resolution reads
first resolution, cabin updatethe current revision
plain resolution with a lockfilethe pinned revision; a pin the index no longer lists is an error naming cabin update
cabin update --package <name>the current revision for <name>; the pinned revision for every other package
--locked, --frozenthe pinned revision; a pin the index no longer lists is an error

Plain resolution never moves a listed pin to another revision of its version: for that lockfile, the pinned revision’s metadata is what the version declares. When a manifest change needs what only a later revision declares, plain resolution chooses another version or fails, and cabin update --package <name> moves the pin.

The version-level fields resolution does not read, such as license and upstream, are recorded for the current revision only. A respin that changes one replaces the version’s value without adding a resolution; a superseded revision’s own declaration remains in its archive’s cabin.toml.

Yanking stays per version: a yanked version is never a new candidate, whatever its revisions. A hosted registry lists only verified revisions, so a pin to one that is not listed behaves like any unlisted pin.

Each entry of a version’s revisions map takes this exact shape:

"9a93b2b7dfdac77c": {
  "checksum": "sha256:9a93b2b7dfdac77c9a93b2b7dfdac77c9a93b2b7dfdac77c9a93b2b7dfdac77c",
  "published-at": "2026-02-02T18:40:07Z",
  "source": {
    "type": "archive",
    "path": "../archives/fmt/fmt-10.2.1-9a93b2b7dfdac77c.zip",
    "format": "zip"
  }
}
FieldRequiredDescription
checksumyessha256:<hex> digest of this revision’s archive bytes, parsed strictly (exactly sha256: followed by 64 lowercase hex characters; any other spelling fails index loading). The revision id must be this digest’s leading hex prefix.
published-atyesNon-empty timestamp recorded by the registry that accepted this revision. Carried verbatim; Cabin never orders revisions by it (the revision pointer names the current one).
sourceyesWhere this revision’s archive lives. See Source artifact.
resolutionnoThis revision’s dependencies, build-dependencies, build-script, features, standards, and links, in the version entry’s encoding and with the same omission defaults, when they differ from the version’s. Absent: the revision resolves exactly as the version does. Schema 2 only, and never on the current revision.

Superseded revisions stay listed, and their archives stay in place, so a lockfile that pins one keeps building. revision and revisions may be absent together - a resolver-only fixture that carries no archives at all. Such a version resolves, but any command that has to materialize it fails.

Source artifact

Each revision’s source block must take this exact shape:

"source": {
  "type": "archive",
  "path": "../archives/fmt/fmt-10.2.1-9a93b2b7dfdac77c.zip",
  "format": "zip"
}
FieldAllowed valuesDescription
type"archive"Local source archives. Other values (HTTP, OCI, Git, …) produce a clear error.
pathnon-empty stringFilesystem path to the .zip archive, which must lie inside the index root. Relative paths are resolved against the directory containing the <package>.json file at load time.
format"zip"Zip archives.

Published artifact filenames are <scope>-<name>-<version>-<revision>.zip for a scoped package and <name>-<version>-<revision>.zip for a bare one, inside a per-package directory. Embedding the revision keeps a downloaded archive self-identifying and lets superseded revisions coexist.

cabin fetch and cabin build copy each archive into the artifact cache, hashing as they go, and reject any archive whose bytes do not match the revision’s checksum. The cache layout is documented in artifacts.md.

Standard metadata

The optional standards block records each library-like target’s declared language-standard interface requirement, so index consumers can read a version’s per-target requirements without downloading the source archive:

"standards": {
  "targets": {
    "fmt": { "interface": { "c": "none", "c++": { "min": "c++17" } } },
    "fmt-header-only": {
      "header-only": true,
      "interface": { "c": "none", "c++": { "min": "c++20" } }
    }
  }
}
  • targets is keyed by the version’s library-like target names (library and header-only kinds); executables, tests, and examples never constrain consumers and are omitted.
  • interface maps a language key ("c", "c++") to a requirement cell. A missing key is unconstrained; "none" marks the target’s headers as not consumable from that language; a { "min": "<level>" } table is a minimum-only requirement, and { "min": "<level>", "max": "<level>" } a bounded inclusive range the consuming code must sit inside (min <= max, validated on read). A missing standards block, or a missing target, is unconstrained everywhere - so every pre-standards entry stays valid unchanged.
  • header-only and gnu-extensions are per-target booleans, each omitted when false. gnu-extensions never affects a requirement.

The stored value is each target’s own declared requirement, not a transitively composed one; max is written exactly when the requirement is bounded. cabin publish derives each cell from the resolved manifest by the rules of post-resolution compatibility, so a header-only target’s inferred minimum is stored like a declared one, and a target that implements no C stores "none" for C unless it declares interface-c-standard. It writes a row for every library-like target, {} when the row is empty, in target-name order with "c" before "c++".

The optional links block records each target’s declared native-library identity claim (manifest.md), so the post-resolution uniqueness check can read a version’s claims without downloading the source archive:

"links": { "z": "z" }
  • Keys are target names (only library targets may claim); values are the claimed identities. Keys satisfy the target-name grammar, values the links identity grammar, and each identity appears at most once - the manifest and publish rules, re-validated on load.
  • Each claimed target must also have a standard metadata row that is not header-only. Publishing writes a row for every library-like target, so a missing row (or a header-only one) marks a claim the manifest’s library-only rule would have rejected; the loader refuses such entries.
  • A missing links block means the version claims nothing, so every pre-links entry stays valid unchanged. An empty block is never written - absence is the empty encoding.

Package with dependencies

{
  "schema": 1,
  "name": "spdlog",
  "versions": {
    "1.13.0": {
      "dependencies": { "fmt": ">=10.0.0 <11.0.0" },
      "yanked": false,
      "revision": "9a93b2b7dfdac77c",
      "revisions": {
        "9a93b2b7dfdac77c": {
          "checksum": "sha256:9a93b2b7dfdac77c9a93b2b7dfdac77c9a93b2b7dfdac77c9a93b2b7dfdac77c",
          "published-at": "2026-02-02T18:40:07Z",
          "source": {
            "type": "archive",
            "path": "../archives/spdlog/spdlog-1.13.0-9a93b2b7dfdac77c.zip",
            "format": "zip"
          }
        }
      }
    }
  }
}

Yanked version

Yanking is version-level: it covers every revision of the version at once.

{
  "schema": 1,
  "name": "fmt",
  "versions": {
    "10.2.1": { "dependencies": {}, "yanked": true },
    "10.1.0": { "dependencies": {}, "yanked": false }
  }
}

cabin resolve will pick 10.1.0 from this index. If every matching version is yanked, the resolver returns “all matching versions of fmt are yanked”. Neither entry here carries revision / revisions, so both are resolver-only: this fixture exercises candidate selection and cannot be fetched.

Validation

Resolution reads only the package documents it needs: those of the manifest’s versioned dependencies and the dependencies they reach, an optional dependency’s only once a feature enables it. No other document is read, so a damaged document for an unrelated package cannot fail the run. The same is true of the sparse HTTP index.

Loading fails when the index path is not a directory, or when a document it reads violates one of these rules:

  • the document has unknown fields
  • schema is neither 1 nor 2
  • the declared name doesn’t equal the filename stem
  • a version key is not a valid SemVer string, or carries SemVer build metadata
  • a dependency requirement is not parseable
  • a revision id is not exactly 16 lowercase hex characters
  • a revision id is not the leading hex prefix of its own checksum
  • a revision’s published-at is empty
  • revisions is present without a revision pointer, or the pointer does not name a listed revision
  • a revision carries resolution in a schema-1 file, or the current revision carries one
  • a source.type is anything other than "archive"
  • a source.format is anything other than "zip"
  • a source.path is empty
  • a standards interface cell carries an empty range (max older than min), or is a bare standard string ("c++17") rather than "none" or a { "min": "<level>", "max": "<level>" } table
  • a links entry has a key outside the target-name grammar, a value outside the links identity grammar (non-empty ASCII letters, digits, ., _, +, and -), or an identity claimed by more than one target of the version
  • an upstream block violates the provenance rules: a non-HTTPS or credential-bearing url, a checksum that is not sha256: followed by 64 lowercase hex characters, a format other than "tar.gz" / "zip", a multi-component strip-prefix, an unsafe copy path, or a patches entry that is unsafe or conflicts with a copy path, another patch, or the root manifest

Not supported yet

The index format deliberately leaves the following out:

  • OCI / GHCR or other remote-archive transports;
  • Git sources;
  • account or credential handling beyond the bearer-token protocol of remote-registry.md;
  • append-only / immutable indexes;
  • artifact signing or trust configuration;
  • platform-specific dependency data beyond the current serialized dependency records;
  • mirror configuration;
  • a cabin-specific JSON schema document; the format is documented here and validated by code, but no formal $schema URL is published.

These are deferred.

Sparse HTTP index

--index-url <url> consumes the same registry-root layout served as static HTTP files. The base URL may include or omit a trailing slash; the loader normalizes it. It must be https, or plain http to a loopback host (localhost, 127.0.0.0/8, ::1) for local testing: the index decides which bytes a fresh resolution pins, so a cleartext index beyond the local machine would let the network choose the dependencies. The rule covers every entry point - --index-url, [registry] index-url, and a [source-replacement] URL - and every download: artifacts come from the index origin, or from a dl the same rule covers.

Request shape:

StepURLPurpose
1GET <url>/config.jsonValidates schema = 2, kind = "file-registry", and the configured packages / archives subdirectories.
2GET <url>/<config.packages>/<name>.json (bare name) or GET <url>/<config.packages>/<scope>/<name>.json (scoped name)One request per package referenced by the manifest’s versioned dependencies and their transitive non-optional dependencies; an optional dependency’s metadata is requested only once resolution enables it.
3GET <artifact-url>Source-archive download for each (name, version, revision) triple cabin fetch / cabin build needs.

The config.json fetched in step 1 recognizes the same optional auth-required / api / dl fields as the local loader (see Registry-root layout); whenever a credential is stored for the index origin, every request in the table to that origin carries it, so an artifact served from a dl on another origin is requested without it - and the hosted registry’s reads work with no credential at all (remote-registry.md).

Source-path resolution for each revision:

  • source.path is resolved against the package metadata URL using RFC 3986 rules. The standard "../archives/<name>/<name>-<version>-<revision>.zip" therefore resolves to <url>/archives/<name>/<name>-<version>-<revision>.zip - the literal path components are joined per RFC 3986; the config.archives field is not substituted into the URL. A scoped package’s document sits one directory deeper, so its canonical "../../archives/<scope>/<name>/<scope>-<name>-<version>-<revision>.zip" climbs one extra level and lands on the same registry root.
  • Absolute or scheme-relative http:// / https:// values are accepted only when the final artifact URL has the same origin (scheme, host, and effective port) as the package metadata URL. Cross-origin artifact URLs and URLs containing userinfo credentials are rejected before any download is attempted.
  • A registry whose config.json declares dl serves its archives from that host instead. The URL resolved above must name a file in the index’s archives directory and carry no query or fragment; its path below the index URL is then appended to dl. With the index at https://index.example.com and "dl": "https://static.example.com", the canonical scoped path downloads from https://static.example.com/archives/<scope>/<name>/<scope>-<name>-<version>-<revision>.zip: dl names the root the directory hangs from, so the directory name is not repeated in it. dl must be https; only an index that is itself a plain-http loopback URL may name a plain-http loopback dl, so a remote index cannot aim cleartext requests at services on the local machine. It carries no userinfo, and may carry a path but no query or fragment. A credential stored for the index origin is not sent to a dl on another origin.

Error mapping:

  • 404 on a package metadata URL -> the package has no versions: a direct dependency on it fails with package "<name>" was not found in index, a transitive requirement surfaces as a resolution conflict, and an unselected version’s dependency on it does not fail the run.
  • 3xx or 5xx -> HTTP index request failed for `<name>`: server returned <code>; redirects are never followed.
  • Malformed JSON -> invalid package metadata from HTTP index for `<name>`: ....
  • Mismatched checksum on a downloaded archive -> the same artifact error (checksum mismatch for ...).

Frozen / offline limits

There is no persistent HTTP metadata cache. Combining --frozen with an effective HTTP index URL, whether from --index-url, [registry] index-url, or source replacement, therefore fails with a clear message:

cannot use --index-url with --frozen: there is no persistent HTTP index metadata cache,
so a frozen run would have to perform network fetches it is not allowed to perform

With no index source configured at all, the default registry would apply. Source replacement applies to it first, exactly like a config URL; a default that still resolves to a URL is refused with its own wording (cannot resolve versioned dependencies with --frozen: no index source is configured, ...), pointing at --index-path.

--locked --index-url does work - the lockfile lives on the local filesystem, and the resolver can validate fetched metadata against it. Full offline / vendoring workflows are separate commands documented in vendoring-offline.md.

End-to-end example

A registry written by cabin publish --registry-dir can be consumed locally with --index-path or served as static HTTP and consumed with --index-url - the reads are the same either way. (A bare-name registry assembled by hand stays readable over both, too.)

# 1. Publish a package into a local file registry.
cabin publish --manifest-path fmt/cabin.toml --registry-dir registry

# 2. Consume it locally...
cabin resolve --manifest-path app/cabin.toml --index-path registry
cabin fetch \
  --manifest-path app/cabin.toml --index-path registry --cache-dir cache
cabin build \
  --manifest-path app/cabin.toml --index-path registry --cache-dir cache \
  --build-dir build

# ...or serve the same directory over static HTTP:
python3 -m http.server --directory registry 8000  # any static server works
cabin resolve --manifest-path app/cabin.toml --index-url http://localhost:8000

Relationship to cabin package

cabin package and cabin publish --dry-run produce a canonical metadata document next to the archive. That document describes exactly one packaging revision: it carries the archive’s checksum and a source.path whose filename already embeds the revision derived from that checksum, alongside the same schema, dependencies, yanked, and standards shape as an index entry. File-registry publish splices it into a <package>.json - adding it to the version’s revisions map, stamping published-at, and recording the earlier revisions’ resolution when the new one changes it - without re-deriving anything else. Packaging and dry-run publishing do not modify any index - see package-format.md.