Installer and releases

• 1: CLI and automation interfaces
• 2: Generated CLI Reference
• 3: Rust Library API
• 4: Installer Contract
• 5: Python MCP runtime contract
• 6: Release Production
• 7: Evidence-bound Release Process
• 8: Installer Threat Model
• 9: v0 Compatibility
• 10: aibox Integration

1 - CLI and automation interfaces

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.

Current v1 alpha commands

The current prerelease supports:

processkit plan
processkit install
processkit update
processkit verify
processkit verify-release
processkit doctor
processkit mcp verify
processkit mcp prepare
processkit mcp prepare --offline
processkit mcp serve --transport stdio
processkit mcp proxy --url http://127.0.0.1:8000/mcp
processkit inspect-compatibility
processkit migrate-v0
processkit recover
processkit uninstall
processkit execute --request request.json

plan, install, update, compatibility inspection, and migrate-v0 currently require an explicit local release directory through --distribution. Mutating commands also require --yes. This makes the alpha suitable for offline use and for callers that already acquire and verify an exact release.

migrate-v0 --plan-only emits exact-release and corpus dispositions without modifying either the source or the empty target. Omit --plan-only and add --yes only after every blocking finding is resolved.

For example:

processkit plan \
  --root . \
  --distribution /path/to/processkit-v1.0.0-alpha.5 \
  --profile managed \
  --harness codex

Target human lifecycle

The human-facing CLI will grow into these lifecycle groups without changing the Python implementation of the MCP servers:

processkit init
processkit plan
processkit install
processkit update
processkit verify
processkit inspect
processkit migrate
processkit recover
processkit uninstall
processkit package
processkit harness
processkit mcp

Human commands will eventually resolve an exact canonical version and verify its signed release metadata before planning. --distribution will remain the explicit offline and development override. Moving branches and unverified latest URLs are not release identities.

The Rust mcp command will diagnose and supervise the installed Python gateway. It will not become a second MCP implementation. Direct uv run .../server.py configurations remain supported.

Stable machine interface

Automation uses:

processkit execute --request request.json

The request and result use the versioned installer schema. The request names the target root, operation, release input, profiles, harnesses, and mutation acknowledgement. The command emits one result envelope. Callers must use its status and the process exit code rather than parse human output.

The execute protocol remains the opaque aibox integration boundary. New human commands may compile their intent into the same internal operations, but they must not silently change the versioned machine contract.

See the installer contract for transaction, ownership, and recovery guarantees and aibox integration for the consumer protocol.

2 - Generated CLI Reference

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

3 - Rust Library API

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.

4 - Installer Contract

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.

Consumers invoke the opaque request/result boundary:

processkit execute --request installer-request.json

The request selects an operation, arbitrary target root, release directory, profiles, harness intent, and explicit mutation acknowledgement. The command prints exactly one JSON result. A non-zero exit and status: invalid indicate an unsuccessful request.

Target-local state belongs in .processkit/state.json; it is never copied back into a release payload. Every mutation uses a target-local lock, staging tree, backups, and persisted action journal. After interruption, a caller runs a recover request; recovery either rolls back the old state or finalizes the new state and refuses ambiguous evidence.

Harness adapters consume the canonical MCP catalogue and own only their named managed keys. Existing unrelated JSON keys survive install and uninstall.

Release creation and verification are local operations. Repository scripts run the authoritative tests, build the archive, sign a release envelope with a locally held Ed25519 key, and verify it against a local trust-store document. The Rust executable verifies the exact signed envelope bytes and archive digest natively. Updates reject downgrades and same-version equivocation. No hosted CI or publication service is part of the contract.

The authoritative local gate is:

scripts/test-installer-local.sh

It includes Rust formatting, Clippy, unit/integration tests, signature and tamper tests, an arbitrary-directory lifecycle pilot, contract validation, package smoke testing, and the derived-project health check.

The implementation is split across focused release, request, planning, transaction, state, compatibility, output, and typed-error modules. A separate reusable Rust library crate and fully documented public API remain future refactoring work.

5 - Python MCP runtime contract

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:

requires-python = ">=3.10"
dependencies = [
  "mcp[cli]>=1.0,<2.0",
  "pyyaml>=6.0",
  "jsonschema>=4.0",
  "jinja2>=3.1",
  "httpx>=0.27",
  "sqlite-vec>=0.1.0",
]

The release manifest records a digest of every server dependency header. Changing a header requires regenerating that manifest and restarting the server.

The release also ships .processkit/installer/runtime/python-uv.json. This deterministic policy is generated exclusively from the MCP servers under the release’s src/context/ producer tree. It records each server header, its dependency profile, and an aggregate digest. Installed projects receive it as .processkit/runtime/python-uv.json.

The release also installs a universal, hash-checked requirements lock at .processkit/runtime/python-requirements.lock. The policy binds its SHA-256. Runtime preparation refuses a missing, symlinked, unhashed, or digest-mismatched lock and passes the lock directly to uv.

Dependency and cache behavior

uv resolves PEP 723 dependencies and stores downloaded artifacts and environments in its user cache. Operators may select a separate cache through UV_CACHE_DIR. The cache must remain outside processkit’s managed project content; normal MCP startup must not modify context/, src/context/, or tracked configuration.

Resolved runtime versions and distributions are locked with hashes. A cold offline installation still requires a prepared cache because wheels are not embedded in the release. Prepare the locked runtime into the selected cache:

processkit mcp prepare --root .
processkit mcp prepare --root . --cache-dir /absolute/cache/path

Then prove that the same policy is usable without network resolution:

processkit mcp prepare --root . --offline
processkit mcp prepare --root . \
  --cache-dir /absolute/cache/path \
  --offline \
  --json

Offline verification fails if the cache directory is absent, symlinked, or cannot satisfy any dependency profile. Preparation validates the installed policy identity, aggregate digest, profile digests, representative server paths, dependency strings, and Python constraints before invoking uv without a shell.

Startup and transport

Direct gateway startup is:

uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  serve --transport stdio

The gateway also supports streamable HTTP on loopback and a stdio proxy. A non-loopback HTTP listener requires an explicit deployment security layer; processkit does not expose it remotely by default.

The v1.x-dev line implements the first read-only native diagnostic:

processkit doctor --root . --json
processkit doctor --root . --category drift

It validates the project root and doctor script, probes uv, launches the authoritative Python doctor without a shell, and wraps its structured result in processkit.projectious.work/runtime/v1alpha1. It intentionally exposes no fix flags.

The v1.x-dev line also implements the native supervision interface:

processkit mcp verify
processkit mcp prepare
processkit mcp prepare --offline
processkit mcp serve --transport stdio
processkit mcp serve --transport streamable-http
processkit mcp proxy --url http://127.0.0.1:8000/mcp

These commands validate a regular, non-symlink gateway path and launch uv with a direct argument vector, without shell interpretation. The child is scoped to the canonical project root and its exit status is preserved. Streamable HTTP and proxy URLs are restricted to explicit loopback hosts; remote exposure remains an operator-owned deployment concern.

Diagnostic contract

The native doctor preserves Python findings, reports whether it is running on a local host or in a container, and lists deferred host-only checks with stable IDs, severity, and remediation. The host-only IDs are host.docker-engine, host.filesystem-permissions, and host.network-release-access.

Runtime failures cover:

• missing or unsupported Python;
• missing or incompatible uv;
• unreadable gateway or shared-library paths;
• invalid PEP 723 metadata;
• unavailable, unsafe, or incomplete runtime cache;
• gateway initialization or startup timeout;
• invalid harness projection;
• optional semantic-index degradation.

Missing optional sqlite-vec acceleration must not be confused with failure of the canonical file-backed entity operations. Diagnostic output must never include environment secrets, provider credentials, private signing material, or private TeamMember memory.

6 - Release Production

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.

Validate and create a release

scripts/release-local.sh v1.0.0-alpha.5 \
  "$HOME/.config/processkit/keys/release.pem" \
  "$HOME/.config/processkit/trust.d/release.pub.pem"

The command runs the complete local validation suite, builds a reproducible archive, creates an integrity envelope, signs it with Ed25519, and verifies the result. It produces the archive, native installer executable, checksum sidecars, release JSON, and signature under dist/. The signed envelope contains a required installerAssets matrix. A local alpha or beta release contains the current Rust host target. Multi-host production uses local Linux and macOS machines to build each executable independently, copies their outputs into one trusted finalization workspace, and then binds the matrix:

scripts/finalize-release-local.sh v1.0.0-alpha.5 \
  /secure/release.pem \
  /secure/release.pub.pem \
  aarch64-unknown-linux-gnu \
  x86_64-unknown-linux-gnu \
  aarch64-apple-darwin \
  x86_64-apple-darwin

Finalization fails if any named asset is absent, duplicated, symlinked, or unsafe. The resulting signature binds every target, filename, digest, and byte size. Each local host executes scripts/build-host-artifact.sh, verifies tag and commit provenance, and natively smoke-tests its binary. Merely naming a target never manufactures or validates it.

Exact-version bootstrap

The non-root bootstrap installs a native executable only after checking its checksum, signed-envelope membership, signature, and the canonical Ed25519 key fingerprint published in release/processkit-v1-signing-public.pem:

scripts/install-processkit.sh v1.0.0-alpha.5

It detects Linux x86_64/ARM64 and macOS x86_64/ARM64, installs to $HOME/.local/bin by default, and refuses floating versions. Supplying the Operators may override the fingerprint only when intentionally selecting a different trusted release identity.

Verify after copying

scripts/verify-release-local.sh \
  dist/processkit-v1.0.0-alpha.5.release.json \
  dist/processkit-v1.0.0-alpha.5.release.sig \
  "$HOME/.config/processkit/trust.d/release.pub.pem"

Copying or publishing these files is a separate operation. Any filesystem, server, removable medium, or artifact host may be used. Publication does not confer trust; the signature and local public key do.

Agent operation

Agents should use explicit absolute key paths, capture exit status, retain the complete stderr log, and report the generated file paths and public-key fingerprint. They must never print or copy private-key contents. A failed local gate stops release creation.

Native consumer verification

The shell verifier remains the human-operable release-side check. The Rust installer also verifies releases against the versioned JSON trust store:

processkit verify-release \
  --envelope dist/processkit-v1.0.0-alpha.5.release.json \
  --signature dist/processkit-v1.0.0-alpha.5.release.sig \
  --trust-store "$HOME/.config/processkit/trust-store.json"

Both verifiers bind the exact envelope bytes, Ed25519 key identity, semantic version, archive filename, byte size, SHA-256, and top-level directory. They also bind every installer target, filename, byte size, and SHA-256, rejecting duplicate targets or files. The envelope separately binds the release descriptor and PROVENANCE.toml inside the archive; extraction verifies both digests and requires the provenance tag to match the release version.

Legacy trees can be inspected independently before installation. See v0 to v1 compatibility inspection .

7 - Evidence-bound Release Process

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:

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.

Phase zero

scripts/maintain.sh release vX.Y.Z --steps phase0

This writes dependency/toolchain state and runs pk-doctor plus the release audit. Errors block. Warnings and actionable findings require a tracked release-deferrals/vX.Y.Z.md with rationale, owner, issue, and expiry.

Candidate checks

scripts/maintain.sh release vX.Y.Z --steps checks

Independent audit, installer, and production-documentation gates run with bounded concurrency and retain separate logs. The documentation gate requires:

• release-notes/vX.Y.Z.md;
• README, contribution, license, security, conduct, maintenance, and support files; and
• a complete Hugo build, generated-link check, and contrast check.

Build and signing

Set absolute paths to the private and public Ed25519 keys:

export PROCESSKIT_RELEASE_PRIVATE_KEY=/secure/release.pem
export PROCESSKIT_RELEASE_PUBLIC_KEY=/secure/release.pub.pem
scripts/maintain.sh release vX.Y.Z --steps build

The build delegates to the existing local release pipeline and stops on any test, artifact, checksum, signature, or package-acceptance failure.

Publication and verification

After reviewing the evidence:

scripts/maintain.sh release vX.Y.Z --steps publish,verify

Publication:

1. rechecks the designated release branch and clean candidate;
2. requires all prerequisite evidence;
3. creates and pushes an annotated tag;
4. creates a GitHub release from tracked curated notes with all matching archive, checksum, signature, key, and native assets; and
5. deploys the production documentation.

Final verification downloads the public assets, checks archive digests, records GitHub release metadata, and records the remote peeled tag.

Recovery and resumption

Rerun the same command on the same candidate. Passed step markers are reused. Changing the commit creates a new evidence directory and reruns the selected steps. Publication is deliberately not inferred from a local green run.

If a tag or release was partially published, inspect remote state before continuing. The orchestrator fails closed when the tag already exists instead of overwriting public history.

Host-only phase

release-host verifies the exact tag, full source commit, and clean checkout before building and natively running processkit --version. It emits the binary, checksum, and local-host provenance. Maintainers run that contract on local x86_64 and arm64 Linux and macOS hosts, then copy the outputs into the finalization workspace. Collected assets are signed into one release envelope; a release must not claim a target without its native smoke evidence.

8 - Installer Threat Model

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.

Before beta, tests must cover archive size/count limits, TOCTOU and symlink races, interrupted application/recovery, malformed provenance, downgrade policy, MCP command-array injection, and secret redaction in plans and state.

9 - v0 Compatibility

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.

Compatibility inspection is read-only. Detection does not mutate the inspected tree and does not authorize an in-place install.

Transition an exact release

Create an empty directory outside the legacy tree, review the compatibility result, and first generate a non-mutating plan:

mkdir /path/to/fresh-v1-project
processkit migrate-v0 \
  --source /path/to/exact-v0-release \
  --root /path/to/fresh-v1-project \
  --distribution /path/to/processkit-v1-release \
  --profile managed \
  --harness codex \
  --plan-only \
  --json

Resolve every blocking finding, review the dispositions and hashes, then omit --plan-only and acknowledge installation:

processkit migrate-v0 \
  --source /path/to/exact-v0-release \
  --root /path/to/fresh-v1-project \
  --distribution /path/to/processkit-v1-release \
  --profile managed \
  --harness codex \
  --yes \
  --json

The command accepts only an exact v0.27.1 or v0.28.4 release match. The target must be empty, separate from the source, and outside the source tree. It installs v1 transactionally in the target and reports the matched manifest, source release, target release, and corpus disposition. The source stays read-only.

The result includes a deterministic corpus plan for every supported project-owned root, including artifacts, bindings, roles, and TeamMembers in addition to actors, decisions, discussions, gates, logs, migrations, notes, scopes, and work items. Each entry binds its source SHA-256 and reports one of:

• copy-compatible for a structurally compatible mutable entity;
• preserve-immutable for a LogEntry or applied Migration; or
• a blocking finding for invalid frontmatter, an unsupported API version, unsafe links, missing identity, or a kind/directory mismatch.

Every entry includes an explicit fieldLoss array. It is empty for the currently accepted v2 envelopes. The planner rejects the migration before installation when any finding is blocked.

Exact v0.27.1 and v0.28.4 release manifests are the ownership baseline. Only files present in the selected source project are planned, every accepted file must carry the expected kind and identity, and ambiguity blocks the complete plan rather than guessing ownership.

After review, the mutating command installs v1 and applies every accepted corpus entry through a second journaled transaction. Mutable entities and immutable LogEntries/applied Migrations are copied byte-for-byte, remain user-owned, and are not added to the installer’s managed-file inventory. Installation state records the source release, compatibility manifest, corpus plan SHA-256, entry count, and complete typed plan. processkit verify re-checks every migrated path against the persisted source digest and reports missing, unsafe, or modified migrated entities as provenance drift.

If the process stops during corpus application, run:

processkit recover --root /path/to/fresh-v1-project --yes --json

Recovery uses the distinct pre-migration and migrated state hashes to roll back partially applied entities without changing the source. The recovered target remains a valid fresh v1 installation; select a new empty target before retrying migrate-v0.

In-place migration remains unsupported. Mixed-root migration is supported only for an exact recognized release into a separate empty target; a structural lookalike or downstream manager lock file cannot establish provenance.

10 - aibox Integration

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:

scripts/test-installer-local.sh
scripts/test-installer-pilot-local.sh
scripts/test-aibox-parity-local.sh

The stable request fields are apiVersion, operation, root, distributionPath, envelopePath, signaturePath, trustStorePath, profiles, harnesses, and yes. Plan, install, and update accept either a development distributionPath or the three signed-release paths. Production consumers use the signed-release form. Mutation operations require yes: true.

The stable result core is apiVersion, status, changes, conflicts, warnings, and errors. Install additionally returns the committed state. Callers must use status and the process exit code, not human output.

Cancellation is process cancellation. A subsequent recover request is the only supported interruption repair path. Retries are safe after recovery; the target lock prevents concurrent mutations. Installation state and transaction evidence contain no private release key.

For the first integration increment, aibox should:

1. build or obtain the standalone executable;
2. validate the shipped schema bundle;
3. replace its provisional fixture call with execute;
4. run plan, install, cancellation/recovery, update, and uninstall in a disposable project;
5. compare normalized direct-CLI and execute-envelope installed state.

The readiness signal for removing the provisional adapter is a tagged processkit prerelease containing this protocol and a passing scripts/test-installer-local.sh result on both repositories.

For M5, pin the immutable v1.0.0-alpha.5 release, not a branch or moving reference. The aibox consumer test must download the archive, release envelope, signature, public key, and matching native installer from that GitHub release, verify the signed envelope, then exercise the opaque request contract. Keep the v0 compatibility bridge enabled; this prerelease is an explicit project opt-in and does not change the default processkit line.