Installer and releases on processkit

CLI and automation interfaces

Mon, 01 Jan 0001 00:00:00 +0000

processkit has two deliberately separate command interfaces. Human lifecycle commands optimize for reviewable output and safe project operation. The machine interface uses a versioned JSON request and result contract for aibox and other automation.

Release and development status: v1.0.0-alpha.5 supports the local lifecycle commands below except doctor and mcp. The v1.x-dev line adds read-only native diagnosis and MCP supervision for the next prerelease. Commands in “Target human lifecycle” remain planned unless listed as current.

Generated CLI Reference

Mon, 01 Jan 0001 00:00:00 +0000

Do not edit this page by hand. Regenerate it with uv run scripts/generate-v1-docs.py.

Native lifecycle CLI for processkit projects

Usage: processkit <COMMAND>

Commands:
 plan Produce a deterministic, non-mutating installation plan
 install Install a verified release into a new or empty target project
 recover Roll back or finalize incomplete installer transactions
 uninstall Remove unchanged files owned by a prior installation
 update Update unchanged managed files from a verified release
 verify-release Verify a signed local release against an explicit local trust store
 verify Verify installed provenance and report managed-path drift
 inspect-compatibility Inspect a legacy processkit tree without mutating it
 migrate-v0 Transition an exact v0 release into a fresh v1 target
 doctor Diagnose the installed project and Python MCP runtime without mutation
 mcp Verify or supervise the shipped Python MCP gateway
 execute Execute one versioned installer request and emit one result envelope
 help Print this message or the help of the given subcommand(s)

Options:
 -h, --help Print help
 -V, --version Print version

Rust Library API

Mon, 01 Jan 0001 00:00:00 +0000

The processkit crate exposes the versioned request envelope used by processkit execute --request. The supported alpha surface is intentionally small:

API_VERSION identifies the machine protocol;
Operation enumerates supported lifecycle operations; and
InstallerRequest constructs and serializes typed request envelopes.

Build and test the API documentation with:

cargo test --doc --locked --manifest-path installer/Cargo.toml
cargo doc --locked --no-deps --manifest-path installer/Cargo.toml

Public items follow semantic versioning within the v1 release line. Modules and functions not reachable from the crate root are internal implementation details and may change between prereleases. Filesystem transactions, release verification, and lifecycle execution remain behind the executable boundary; the library does not offer an alternate mutation path.

Installer Contract

Mon, 01 Jan 0001 00:00:00 +0000

Alpha.4 status: Implemented for explicit local distributions and signed local releases. Canonical online release acquisition is not implemented.

The standalone installer consumes only a release directory or verified archive explicitly supplied by its caller. It has no built-in release URL, package layout, MCP inventory, or harness policy.

The release-owned contract is under .processkit/installer/. Protocol processkit.projectious.work/installer/v1alpha1 supports deterministic planning plus transactional install, update, uninstall, and recovery. copy/v1 and preserve-user/v1 are the closed payload operations.

Python MCP runtime contract

Mon, 01 Jan 0001 00:00:00 +0000

Python is an intentional processkit runtime dependency. It implements the MCP servers; it is not required by the Model Context Protocol itself. The native Rust CLI owns installation and lifecycle safety. Native diagnostics and process supervision wrap that Python implementation; they do not reimplement MCP behavior.

Current alpha requirements

Python 3.10 or newer must be discoverable by uv.
uv must support PEP 723 script metadata.
The installed gateway script and processkit shared Python library must be readable from the selected project root.
The first preparation may require network access to populate the uv cache.
Direct uv run startup remains a supported compatibility and development interface.

Every shipped MCP entry point declares its Python constraint and dependencies in a PEP 723 block. The gateway currently declares:

Release Production

Mon, 01 Jan 0001 00:00:00 +0000

The v1 release path is agent-first, human-operable, and entirely local. Maintainer-controlled machines invoke the same repository scripts and bind their native results to one tagged commit. No GitHub Actions or hosted build service participates.

One-time key setup

Keep the private key outside the repository. The public key may be copied to the local trust store of every machine that installs official releases.

scripts/processkit-keygen-local.sh \
 "$HOME/.config/processkit/keys/release.pem" \
 "$HOME/.config/processkit/trust.d/release.pub.pem"

Back up the private key securely. Losing it prevents producing a release under that identity. Disclosing it requires creating a new key identity and removing the compromised public key from local trust stores.

Evidence-bound Release Process

Mon, 01 Jan 0001 00:00:00 +0000

Issue #151 defines the aibox-style release ritual adopted by processkit.

Version-line authority

The requested semantic version determines the only branch permitted to tag:

Version	Required branch
stable v0	`v0.x-release`
v1 alpha, beta, or RC	`v1.x-pre-release`
stable v1	`v1.x-release`

Resolve the mapping without mutation:

scripts/maintain.sh release-branch v1.0.0-alpha.5

Promotion into protected branches happens through pull requests. Never force-push a release branch.

Candidate evidence

Evidence belongs to an exact candidate:

dist/release-evidence/<version>/<commit>/
├── binding.json
├── RELEASE-STATE.md
├── RELEASE-DOCTORS.md
├── logs/
└── <step>.passed

The binding records version, commit, clean tree, branch, Rust, Python, uv, and host target. A step marker is reused only within that binding.

Installer Threat Model

Mon, 01 Jan 0001 00:00:00 +0000

Alpha.4 status: Traversal, symlink, forged-journal, signature, digest, downgrade, same-version equivocation, and interruption paths have automated coverage. The “before beta” items below remain open hardening targets.

The installer treats an archive, descriptor, manifest, catalog, adapter, and target filesystem as untrusted until validated. It must reject absolute or parent-traversal paths, archive links and path escapes, duplicate normalized destinations, unsupported operations, unverified assets, and target symlink escapes. It must not execute release-supplied code.

v0 Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

v1.x development status: Exact-release inspection and a guarded fresh-target transition are implemented. Native in-place migration and automatic legacy-entity transformation are not supported.

The v1 installer identifies legacy processkit evidence without consulting aibox, harness, devcontainer, or MCP configuration files.

processkit inspect-compatibility \
 --root /path/to/legacy-tree \
 --distribution /path/to/processkit-v1-release \
 --json

An exact-release result requires every immutable anchor in a shipped compatibility manifest to match. The beta manifests cover v0.27.1 and v0.28.4 release trees. A partial installed project may be classified only as legacy-project-candidate; its exact version is never guessed.

aibox Integration

Mon, 01 Jan 0001 00:00:00 +0000

Alpha.5 status: The opaque request/result protocol and direct-CLI/aibox installed-state parity contract are implemented. The v0 compatibility bridge remains available for gradual downstream adoption.

aibox should treat processkit as an opaque local executable. It creates a versioned JSON request, invokes processkit execute --request <path>, parses the single JSON result, and does not duplicate processkit ownership policy.

The producer integration checkpoint is the schema bundle under src/.processkit/installer/schemas/, the executable built from installer/, and these local gates: