Two-hour design-partner path

Run one bounded action through approval, controlled execution, a separate read-only observation, and offline evidence verification. The first run uses a synthetic local GitHub emulator, not GitHub itself. It needs no real GitHub token, performs no production write, and does not connect a Hosted project. Use Get started for the Hosted onboarding path.

1. Check prerequisites and initialize

You need Node.js 20 or newer, npm, Python 3.10 or newer with pip, and Docker with Compose v2 running Linux containers. The host ports 4311 and 4312 must be available. Initialization downloads the published package; a private Witnora source checkout and a global CLI installation are not required.

The commands below use the tested release 0.20.13. Start in a writable customer directory, then enter the generated kit and run all remaining commands there:

npx --yes witnora@0.20.13 design-partner init github-pr-merge --out witnora-design-partner
cd witnora-design-partner

Expected result: QUICKSTART.md, docker/, verifiers/python/, trust/, secrets/, and .env.example are generated. The runtime and verifier are bundled in the kit. Keep secrets/ and .env out of source control. Compare the pinned root fingerprint with the reviewer through a separate channel; accepting a root from the same packet is not independent trust verification.

2. Load the local emulator configuration

The generated .env.example contains dummy local-only credentials. Copy it to .env and load it into the terminal. Do not substitute live provider keys for this first run.

Bash or zsh:

cp .env.example .env
set -a
. ./.env
set +a

PowerShell:

Copy-Item .env.example .env
Get-Content .env | ForEach-Object {
  if ($_ -match '^([A-Z][A-Z0-9_]*)=(.*)$') {
    [Environment]::SetEnvironmentVariable($Matches[1], $Matches[2], 'Process')
  }
}

Create a Python virtual environment:

python -m venv .venv

Activate it with . .venv/bin/activate in Bash or zsh, or .venv\Scripts\Activate.ps1 in PowerShell, then install the bundled verifier:

python -m pip install ./verifiers/python

3. Authorize and inspect before writing

Issue the short-lived approval and single-use execution Grant locally. Signing private keys stay in secrets/; the runtime uses only its assigned keys.

node docker/runtime/dist/cli.js design-partner authorization issue --dir .
docker compose --env-file .env -f docker/compose.yml up -d --build target-sandbox probe
node docker/runtime/dist/cli.js design-partner doctor --dir .
node docker/runtime/dist/cli.js design-partner privacy inspect --dir .
node docker/runtime/dist/cli.js design-partner trust inspect --dir .
node docker/runtime/dist/cli.js design-partner dry-run --dir . --target-url http://127.0.0.1:4311

Expected result: the configuration checks pass and dry-run reports No target write performed. Stop at an incomplete check and use its diagnostic before acceptance. The explicit --env-file supplies Compose; loading .env in the terminal supplies the host CLI commands.

The Probe receives a read credential and its own signing secret. The Gateway receives a separate write credential and its assigned signing secrets. The root private key is not mounted into a runtime container.

4. Execute one sandbox action and verify its packet

docker compose --env-file .env -f docker/compose.yml --profile acceptance run --rm gateway-acceptance
docker compose --env-file .env -f docker/compose.yml --profile acceptance run --rm offline-verifier
node docker/runtime/dist/cli.js design-partner verify-offline --dir . --packet acceptance/witnora-evidence-packet-v0.2.json --root trust/pinned-root.json --revocation-journal trust/revocation-journal.json
python -m witnora_verifier.cli evidence acceptance/witnora-evidence-packet-v0.2.json --root trust/pinned-root.json --revocation-journal trust/revocation-journal.json
node docker/runtime/dist/cli.js design-partner collect-support-bundle --dir .
node docker/runtime/dist/cli.js design-partner pilot-report --dir .

Expected result: one target transition, one separately observed outcome, and TypeScript and Python verifier PASS. The container verifier runs without network access or private signing keys. The packet is already exported under acceptance/; no private source tree or manual volume-copy command is needed.

Read the packet's limitations: recording, controlled execution, observed outcome, and signature integrity are different claims. INTERNAL review is not an external certification. This emulator result does not prove a live GitHub merge, Shopify cancellation, or Stripe refund occurred.

After reviewing the retained evidence, stop this kit's services:

docker compose --env-file .env -f docker/compose.yml down

5. Optional live GitHub read-only preflight

This separate path inspects one dedicated sandbox pull request. It does not merge, mutate, or produce live execution acceptance evidence. GitHub's merge endpoint cannot atomically enforce the signed base SHA, required-check set, and Witnora Grant at the write boundary, so v0.2 exposes no live write command.

Place a real read-only WITNORA_GITHUB_READ_CREDENTIAL in your local secret store. Set WITNORA_LIVE_GITHUB_ALLOWLIST to the exact owner/repository and WITNORA_LIVE_GITHUB_PREFLIGHT to 1 in the invoking process. The pull request's base must be neither main nor master. Never paste credentials into evidence or a support message.

node docker/runtime/dist/cli.js design-partner prepare-live-github --dir . --repository owner/dedicated-sandbox --pull-request 7

This changes the kit's declared target to the inspected live snapshot. Keep that kit separate from the synthetic acceptance kit. The snapshot is for operator review; it is not a Grant or proof that a later merge used that state. Connecting another real provider requires its own controlled write binding and separate read-only verification, reviewed for that exact workflow.