---
title: "Tool packs"
description: "tool-pack.v1 (proposed, ADR 0064; built): the unit a user downloads, <name>-<version>-<os>-<arch>.tar.gz, a strict deterministic ustar holding pack.json (kind tool, helper or engine; os, arch, min_gateway, min_client, requires, team_id, entitlements, license, source commit, check report digest, sha256 per file) and its files; tools-index.v1.json lists packs and revoked versions and is signed with ssh-keygen -Y sign -n vulpine-tools-index by the operator's hardware key; vulpine tool pack builds only what vulpine tool check passes, and vulpine tool verify runs every install-time check in order (index signature, archive sha256, per-file sha256, revoked, os and arch, codesign Team ID, lint) with a typed reason per refusal, running nothing from the pack."
type: "living"
source: "docs/contracts/tool-pack.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

tool-pack.v1 — the unit a user downloads: one strict tar.gz, its pack.json, and the signed tools index

- Status: **accepted** with ADR 0064, version 1.0. `vulpine tool pack` builds a pack
  and `vulpine tool verify` checks one (`crates/vulpine_cli/src/pack.rs`, `pack_verify.rs`, `pack_verbs.rs`,
  `ustar.rs`). The gateway's pack manager installs a pack's helper and engine archives, behind `[packs] enabled =
  false` ([extension-pack.v1](/docs/contracts/extension-pack.v1)). The signed first-party index is not published yet.
- Scope: what a pack holds, how its bytes are checked, and the index that says which packs exist. Who may call an
  installed tool is [tool-index.v1](/docs/contracts/tool-index.v1) and its policy file. How a tool answers is [tool.v1](/docs/contracts/tool.v1).


## The archive

`<name>-<version>-<os>-<arch>.tar.gz`: gzip over a POSIX ustar.

| path | what |
|---|---|
| `pack.json` | the pack's record (below) |
| `tool.toml` | a tool pack's tool.v1 manifest: `handler.kind = "cli"`, `exec = "bin/<program>"`, `handler.digest` pinned |
| `bin/…` | the programs. A Mach-O is arm64, Developer ID signed by the pinned team, with the hardened runtime |
| `<Name>.app/…` | optional, when a privacy grant needs a bundle |
| `golden/…` | the tool's golden calls |
| `LICENSE` | required |
| `*.md` | the guide and any other top-level notes |
| `runtime/…` | an engine pack's runtime or payload |

What the reader refuses (`archive_invalid`):

- any entry that is not a regular file: a directory, a link, a device, or a pax or GNU header;
- a header that is not `ustar\0` `00`, or whose checksum is wrong;
- a path that is absolute, has an empty, `.` or `..` component, is not printable ASCII (or holds a space or `\`), or
  is longer than 256 bytes;
- a path given twice;
- a mode other than 0644 or 0755;
- a file over 4 GiB, or more than 20,000 entries;
- non-zero padding, a missing end marker, or bytes after it.

A path outside the layout above is `layout_invalid`.

The writer sorts entries by path and writes uid and gid 0, no owner names, mtime 0 and a gzip header with mtime 0. The
same folder always gives the same bytes.

## pack.json

```json
{
  "schema": "vulpine.pack.v1",
  "name": "plant_pack", "kind": "tool", "version": "1.2.0",
  "os": "darwin", "arch": "arm64", "min_gateway": "0.1.0", "min_client": "0.1.0",
  "requires": [], "team_id": "JJN98M2477", "entitlements": [], "license": "MIT",
  "source_commit": "0123456789abcdef0123456789abcdef01234567",
  "check_report_digest": "sha256:…",
  "helper": null,
  "files": { "LICENSE": "sha256:…", "bin/plantctl": "sha256:…", "golden/list_ok.json": "sha256:…", "tool.toml": "sha256:…" }
}
```

| field | rule |
|---|---|
| `kind` | `tool`, `helper` or `engine` |
| `name` | a tool pack: the tool's name (`^[a-z][a-z0-9_]{1,63}$`). A helper or engine: its program (`vulpine-ambient`, `-` allowed) |
| `version`, `min_gateway`, `min_client` | semver `x.y.z` |
| `os`, `arch` | `darwin` or `linux`; `arm64` or `x86_64`. The app installs `darwin` / `arm64` only; the others exist for the fleet probe |
| `team_id` | ten upper-case letters or digits |
| `requires` | tokens such as `gateway`, `tcc:<grant>`, `model:<id>`, `host:<name>` |
| `entitlements` | the entitlement keys the programs are signed with |
| `source_commit` | 40 lower-case hex, or null |
| `check_report_digest` | a tool pack's: the sha256 of `vulpine tool check --json`'s report with every `ms` key removed. Null for a helper or engine |
| `helper` | a helper or engine's `{config_key, exec}`: `config_key` is `section.key` and `exec` a listed file. Null for a tool |
| `files` | every other file in the archive, `path: "sha256:<hex>"`. It must include `LICENSE`, and `tool.toml` for a tool pack. It never lists `pack.json` |

A v1 reader refuses an unknown field. A pack that needs a new field raises `min_gateway` with it.

## pack.toml: what `vulpine tool pack` reads

```toml
schema = "vulpine.pack-source.v1"   # optional
kind = "tool"                       # tool | helper | engine
os = "darwin"
arch = "arm64"
min_gateway = "0.1.0"
min_client = "0.1.0"
team_id = "JJN98M2477"
license = "MIT"
requires = []
entitlements = []
# a helper or engine only:
# name = "vulpine-ambient"
# version = "1.0.0"
# config_key = "ambient.worker_bin"
# exec = "bin/vulpine-ambient"
```

A tool pack takes its name and version from its tool.toml. A `name` or `version` in pack.toml must agree with them.
Unknown keys are refused.

## `vulpine tool pack <dir>`

`vulpine tool pack <dir> [--out <folder>] [--source-commit <sha>] [--url-base <url>] [--json]`

1. It reads pack.toml.
2. It walks the folder. Hidden files are skipped and listed in `skipped`. A symlink (`symlink_in_source`), a
   `pack.json`, or a path outside the layout (`layout_invalid`) is refused.
3. A tool pack runs `vulpine tool check` and is refused on any finding (`check_failed`, naming the rules and
   goldens). Its handler must be `cli`, with `exec` inside the pack and listed with `handler.digest`'s sha256
   (`manifest_mismatch`).
4. It hashes every file, writes pack.json, and checks it with the same validator verify uses.
5. It writes the archive to a hidden sibling, reads it back through the verifier's archive layer, and renames it into
   place.
6. It prints `vulpine.tool-pack.v1`: the archive's name, sha256 and size, the pack.json, and the `index_entry` CI adds
   to the index.

Exit codes: 0 built, 1 refused, 2 I/O, 64 usage.

## tools-index.v1.json and its signature

```json
{
  "schema": "vulpine.tools-index.v1", "generated_at": "2026-11-02T21:00:00Z", "channel": "stable", "min_app": "1.0.0",
  "tools": [ { "name": "plant_pack", "kind": "tool", "version": "1.2.0", "os": "darwin", "arch": "arm64",
               "url": "https://…/plant_pack-1.2.0-darwin-arm64.tar.gz", "sha256": "sha256:…", "size": 1234,
               "team_id": "JJN98M2477", "capabilities": [], "egress": [], "approval": "free", "requires": [],
               "min_gateway": "0.1.0", "attestation": null } ],
  "revoked": [ { "name": "plant_pack", "version": "1.1.0", "reason": "…" } ]
}
```

- **Entries.** An entry is found by the archive's file name, which is the last segment of `url`. A name, version, os
  and arch listed twice refuses the index. A reader ignores fields it does not know.
- **Packs.** An optional `packs` array lists first-party extension packs, each pointing at its
  `extension-pack.json` record. An older reader ignores it. Its entries and checks are
  [extension-pack.v1](/docs/contracts/extension-pack.v1)'s.
- **Signing.** `ssh-keygen -Y sign -n vulpine-tools-index -f <key> tools-index.v1.json` writes
  `tools-index.v1.json.sig`. The key lives on the operator's hardware: a 1Password SSH key behind biometrics, or a
  YubiKey `sk-ssh-ed25519` key. CI never holds it.
- **The allowed-signers file.** The app pins it, one line per key:
  `release-primary@vulpine namespaces="vulpine-tools-index" ssh-ed25519 AAAA…`. The pins are
  `crates/vulpine_cli/pins/tools-index.allowed_signers`, embedded in the CLI: the 1Password key as
  `release-primary@vulpine` and the YubiKey as `release-backup@vulpine`. `vulpine tool verify` uses them when
  `--allowed-signers` is not given.
- **Verifying.** `/usr/bin/ssh-keygen -Y find-principals` names the signer, then `-Y verify -n vulpine-tools-index -I
  <principal>` checks the bytes. The environment is cleared. The index's bytes are read once and piped in, so the
  bytes verified are the bytes parsed.

## `vulpine tool verify <archive>`

`vulpine tool verify <archive> [--index <json> --sig <sig> [--allowed-signers <file>]] [--os darwin] [--arch arm64]
[--team-id <id>] [--gateway-version <x.y.z>] [--json]`

- **Defaults.** The host's os and arch, and team `JJN98M2477`.
- **Order.** The checks run in the order below and stop at the first refusal. Later checks read `not_reached`.
- **Without an index.** Without `--index`, checks 1, 2 and 4 are `skipped` and the report says so. The three index
  flags go together.
- **Exit codes.** 0 verified, 1 refused, 2 the archive does not open, 64 usage.

| # | check | refuses with |
|---|---|---|
| 1 | `index_signature` | `index_unreadable`, `index_signature_invalid` (an unlisted key, an edited index, the wrong namespace), `index_invalid` |
| 2 | `archive_sha256` | `not_in_index`, `archive_sha256_mismatch` (sha256 or size) |
| 3 | `files` | `archive_invalid`, `pack_json_invalid`, `layout_invalid`, `file_missing`, `file_unlisted`, `file_sha256_mismatch`, `index_mismatch` (pack.json's name, version, kind, os, arch or team is not the entry's) |
| 4 | `revoked` | `revoked`, with the index's reason |
| 5 | `platform` | `os_mismatch`, `arch_mismatch` (pack.json, or a Mach-O without the host's cpu type, fat files read slice by slice), `gateway_too_old` |
| 6 | `code_signature` | `team_id_mismatch` (pack.json or codesign's TeamIdentifier), `codesign_failed` (`codesign --verify --strict`), `hardened_runtime_missing`, `scratch_unwritable` |
| 7 | `lint` | `lint_failed` (the kit's lint rules), `manifest_mismatch` (another name or version, a non-cli handler, or an `exec` that is not a listed 0755 file with `handler.digest`'s sha256) |

How the code signature is checked:

- Each Mach-O outside a bundle, and each `.app` bundle holding one, is extracted to a 0700 scratch folder (under
  the system temp folder) and hashed again against pack.json.
- Codesign then reads exactly the verified bytes. The scratch folder is removed before verify answers.
- A pack without a Mach-O passes this check on its pack.json alone, and the report says so.

Verify runs nothing from the pack. The golden calls run when the pack is built, and the tool manager reruns them as
its preflight. The report, `vulpine.tool-verify.v1`, has these fields:

- the archive's file name, its sha256 and size;
- the pack's identity;
- the signer's principal;
- one line per check, `{check, status, detail}`;
- `refused {check, reason, detail}`.

It names files by their pack paths and never by an absolute path.

## Versions

A field added to the index is a minor revision. A field added to pack.json moves `min_gateway`. Any change to the
archive's rules, to the signature namespace, or to the order of the checks is tool-pack.v2.

