Getting Started

• 1: Installing
• 2: Install and Use the v1 Alpha
• 3: Your First Entity

1 - Installing

v1 alpha

v1.0.0-alpha.5 is installed with the native Rust lifecycle CLI from an explicitly downloaded, signed release. The alpha does not yet have an online version resolver or one-command bootstrap installer.

Use the complete v1 alpha installation and first-project tutorial . It verifies the signed envelope, checks both artifact digests, previews the plan, installs a selected profile, verifies managed state, and connects the Python MCP gateway.

The current command shape is:

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

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

Do not copy the v1 payload by hand. The CLI supplies transaction, ownership, recovery, and conservative uninstall evidence that manual copying cannot.

Stable v0 and managed aibox projects

Existing v0 projects remain supported and should stay pinned to their current stable version until the v1 migration path is complete. aibox remains an optional downstream installer and integrator; it is not required to build, test, or run processkit.

See v0 compatibility and aibox integration before changing an existing project.

After installation

Python and uv remain runtime prerequisites for MCP:

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

Use MCP tools for entity writes. They validate schemas and transitions and produce the required audit events.

2 - Install and Use the v1 Alpha

This tutorial installs the exact v1.0.0-alpha.5 release into a new project. Linux and macOS on x86_64 and arm64 are supported.

1. Check prerequisites

uname -m
python3 --version
uv --version
git --version
jq --version

Python 3.10 or newer, uv, Git, curl, tar, a SHA-256 utility, openssl, and jq are required.

2. Download the exact release

mkdir -p "$PWD/.processkit-download/v1.0.0-alpha.5"
cd "$PWD/.processkit-download/v1.0.0-alpha.5"

release_url="https://github.com/projectious-work/processkit/releases/download/v1.0.0-alpha.5"
for asset in \
  processkit-v1.0.0-alpha.5.tar.gz \
  processkit-v1.0.0-alpha.5.tar.gz.sha256 \
  processkit-v1.0.0-alpha.5.release.json \
  processkit-v1.0.0-alpha.5.release.sig \
  processkit-v1.0.0-alpha.5-public.pem
do
  curl -fL "$release_url/$asset" -o "$asset"
done

The release is exact-pinned. Do not replace the tag with latest.

3. Verify checksums

sha256sum -c processkit-v1.0.0-alpha.5.tar.gz.sha256

The command must report OK.

4. Install the CLI locally

curl -fLO \
  https://raw.githubusercontent.com/projectious-work/processkit/v1.0.0-alpha.5/scripts/install-processkit.sh
chmod +x install-processkit.sh
./install-processkit.sh v1.0.0-alpha.5
export PATH="$HOME/.local/bin:$PATH"
processkit --version

No root access is required. Add $HOME/.local/bin to your shell PATH if it is not already present.

5. Verify the signed release

mkdir -p "$PWD/trust"
key_id="d35516ccd7be9efad6579c5f6c2ab8ba1a59f18d563f339e62e1cef9a5f9a1eb"
cp processkit-v1.0.0-alpha.5-public.pem \
  "$PWD/trust/v1.pub.pem"

jq -n --arg key_id "$key_id" '{
  apiVersion: "processkit.projectious.work/local-trust/v1alpha1",
  kind: "TrustStore",
  keys: [{
    keyId: $key_id,
    algorithm: "Ed25519",
    publicKeyFile: "v1.pub.pem",
    status: "active"
  }]
}' >"$PWD/trust/trust-store.json"

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

For organizational use, obtain the public key through an independently trusted channel. Publishing a key beside an artifact makes verification reproducible but does not by itself establish publisher identity.

6. Extract the distribution

tar -xzf processkit-v1.0.0-alpha.5.tar.gz
distribution="$PWD/processkit-v1.0.0-alpha.5"

The extracted directory is the required local --distribution input.

7. Create a project and review the plan

project_root="$PWD/../../../processkit-alpha-project"
mkdir -p "$project_root"
git -C "$project_root" init

processkit plan \
  --root "$project_root" \
  --distribution "$distribution" \
  --profile managed \
  --harness codex \
  --format human

plan is non-mutating. Review the selected profile, managed paths, and harness projection before proceeding. Replace codex with claude when that is your harness.

8. Install and verify

processkit install \
  --root "$project_root" \
  --distribution "$distribution" \
  --profile managed \
  --harness codex \
  --yes

processkit verify --root "$project_root"
git -C "$project_root" status --short

The installer owns only declared managed paths and harness keys. It records ownership in .processkit/state.json; unrelated harness configuration and project files are preserved.

9. Start using MCP

Restart the selected harness so it reads the installed projection. If you need a direct development fallback, run the Python gateway from the project:

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

In the harness, ask:

Use processkit to create a medium-priority task WorkItem titled “Evaluate processkit v1 alpha”, then read it back.

Continue with Your First Entity for transitions, decisions, relationships, and queries.

10. Update, recover, or uninstall

Preview a new exact distribution before updating:

processkit plan \
  --root "$project_root" \
  --distribution /path/to/new/exact/distribution \
  --profile managed \
  --harness codex

processkit update \
  --root "$project_root" \
  --distribution /path/to/new/exact/distribution \
  --yes

After an interrupted mutation:

processkit recover --root "$project_root" --yes

To remove only unchanged, provably managed content:

processkit uninstall --root "$project_root" --yes

Changed and user-owned files are preserved and reported.

Alpha.4 limitations

• Only Linux ARM64 GNU has a published native executable.
• Release acquisition and trust-root distribution are manual.
• Human commands require a local distribution directory.
• Native doctor, migrate, package, harness, and mcp command groups are not implemented.
• Python and uv remain required for MCP.
• v0-to-v1 migration is evidence and compatibility inspection only; do not migrate an existing v0 project in place.

Track the exact status in the issue #135 implementation review .

3 - Your First Entity

Create the first WorkItem through processkit’s MCP tools. Do not hand-edit canonical entity files: the management tool validates the schema, applies the storage policy, and writes the audit event as one governed operation.

Prerequisites

• Complete the v1 alpha tutorial .
• Start a new harness session after the installer writes its managed MCP projection.
• Confirm the processkit-gateway tools are visible.

Create a WorkItem

Ask your MCP-capable agent:

Create a medium-priority task WorkItem titled “Evaluate processkit v1 alpha” with acceptance criteria to verify installation, record one decision, and test an update plan.

The agent should route the request and call create_workitem. A successful response includes an ID and canonical path, for example:

BACK-curious-quail
context/workitems/2026/07/BACK-curious-quail.md

Read and transition it

Ask:

Read BACK-curious-quail through processkit, then transition it from backlog to in-progress.

The transition tool checks the WorkItem state machine and records its event. An invalid transition is rejected rather than silently changing the file.

Record and query a decision

Ask:

Record the accepted decision that this project will evaluate v1.0.0-alpha.5 in an isolated branch, link it to BACK-curious-quail, and query both entities back.

This exercises the core v1 user journey: governed write, relationship, audit event, and indexed read over visible project files.

Inspect the result

The files remain readable in Git:

git status --short
processkit verify --root .

processkit verify checks installer-managed content. Domain MCP tools and pk-doctor check project entities; a native processkit doctor command is planned but is not part of alpha.5.

Next

• Review MCP server operation .
• Learn the entity model .
• Read the alpha.5 limitations .