Headless operations guide

01 · What this walkthrough demonstrates

New to Headless? Read one actual Work in six steps. Each step connects the operator’s action, the recorded response, its meaning and the reason to continue. You can copy selected fields or download the same excerpts. Return here for command templates and operational prerequisites.

On 4 October 2026, one isolated local R234 candidate completed the automated part of CREATE_AUDIT_ARTIFACT and returned a Work awaiting human acceptance. This operation creates a structured local audit artifact; it does not inspect arbitrary customer files. The lab was initialized from a matched candidate installer and started using its generated startup descriptor. Those development delivery paths are not customer installation instructions.

Reading format: Headless uses a recorded-run guide with selected actual CLI fields. It is a documentation reader, not a live session or terminal screenshot. Your IDs, paths and hashes will differ. The commands below describe the successful route; the observed input correction remains in the error and correction section.

The local exercise and guide were subsequently approved in conversation. The product’s last observed state remains AWAITING_HUMAN_ACCEPTANCE; that separate approval did not update product state. The service was stopped after evidence collection.

02 · Obtain the operating handoff and start state

1. Ask the delivery contact for the installed packrctl executable, matching service release and exact private local socket. Confirm the supported platform and operator account.
2. Ask the service operator to confirm that the intended service is running, or to perform the supplied startup procedure within their authority. These query commands do not start it. Do not reuse a different installation’s endpoint.
3. Ask the administrator to confirm permission for CREATE_AUDIT_ARTIFACT and the Work owner to supply one unused approved key, a private writable working directory and a reviewer.
4. Confirm local report-file access or an approved artifact handoff with the service operator. If an item is missing, obtain it from its owner before continuing.

Use the supplied local client environment and operator account. A local socket is not a remote connection. The R234 lab result does not establish customer r232 installation or administrator provisioning.

03 · Point every command at the same service

In a fresh private working directory, replace both path placeholders with the supplied absolute paths. Keep this shell and account for the whole walkthrough. The files below capture stdout and can contain private operating details; retain them locally and do not publish the full responses.

PACKRCTL="/ABSOLUTE/SUPPLIED/PATH/packrctl"
SOCKET="/ABSOLUTE/SUPPLIED/PATH/control-plane.sock"
"$PACKRCTL" --help
"$PACKRCTL" --socket "$SOCKET" status --json > status.json
"$PACKRCTL" --socket "$SOCKET" health --json > health.json
HEALTH_EXIT=$?
printf '%s\n' "$HEALTH_EXIT"

Observed: status reported RUNNING; health reported liveness READY, readiness UNKNOWN with AUTHORITY_READINESS_OBSERVATION_UNAVAILABLE, and runtime UNKNOWN with LIVE_RUNTIME_OBSERVATION_UNAVAILABLE. Health exited 1. The exact R234 projection returned unknown authority/runtime observations; this was not a Work admission decision. Overall readiness was not proven.

For this separately approved local exercise, the normal operation admission path evaluated the submission in step 4. Do not generalize this to permission to ignore an unknown prerequisite on another installation. If your release or reason differs, retain the response and ask the operator before submission.

Read the corresponding actual result in the step-by-step reader.

04 · Submit the approved audit operation once

Replace the key placeholder with the unused key assigned to this intentional operation. Keep the supported intent text exactly as shown. This command prepares and executes Work and writes local records; it is not a read-only check. Use fresh output filenames for a later separately approved exercise so earlier evidence is preserved.

WORK_KEY="REPLACE_WITH_ONE_UNUSED_APPROVED_KEY"
"$PACKRCTL" --socket "$SOCKET" work run CREATE_AUDIT_ARTIFACT "create audit artifact" "$WORK_KEY" --json > work-run.json
RUN_EXIT=$?
printf '%s\n' "$RUN_EXIT"

Open work-run.json locally. Find result.work.work_id and retain that exact value with your request key. If the response is missing or ambiguous, go to reconciliation before any new submission. A zero command exit alone does not prove the Work outcome.

Actual local R234 response, selected fields; other fields omitted:

{
  "result": {
    "work": {
      "state": "AWAITING_HUMAN_ACCEPTANCE",
      "work_id": "work-headless-c36fddb388d8599d9f5e70e40296eae13ccfa8ddaccf3976daacfa18e2ce373e"
    },
    "reports": [
      {
        "final_result": "AUTOMATION_COMPLETED_HUMAN_ACCEPTANCE_PENDING"
      }
    ],
    "execution_retry_allowed": false,
    "human_acceptance_claimed": false,
    "replayed": false
  }
}

The automated work completed and did not replay an earlier result. Human acceptance remains pending, and automatic execution retry is not permitted. Continue by reading this same Work.

Read the corresponding actual result in the step-by-step reader.

05 · Find and show the exact returned Work

Copy the full value from result.work.work_id into WORK_ID. Do not copy an ID from an example or derive one from the key. Run both queries with the same executable, socket and account.

WORK_ID="PASTE_EXACT_result.work.work_id_FROM_work-run.json"
"$PACKRCTL" --socket "$SOCKET" work list --limit 10 --json > work-list.json
"$PACKRCTL" --socket "$SOCKET" work show "$WORK_ID" --json > work-show.json

1. In work-list.json, locate that exact ID in works[].work_id.
2. In work-show.json, compare work.work_id, reports[].work_id and selected_report.canonical_report.work_id with WORK_ID.
3. The observed local run matched across submission, list and show, with work.state equal to AWAITING_HUMAN_ACCEPTANCE. Continue to report review.

If the last 10 items omit the ID, show the saved ID directly or use the documented list limit up to 100. A missing result is a scope/reconciliation question, not a reason to submit again. Preserve the original request and ask support if the exact Work cannot be identified.

Observed match in this exercise: work-headless-c36fddb388d8599d9f5e70e40296eae13ccfa8ddaccf3976daacfa18e2ce373e

Read the corresponding actual result in the step-by-step reader.

06 · Read the outcome before claiming completion

Within selected_report.canonical_report, read the following fields together. This is an actual local R234 excerpt with other fields omitted.

{
  "work_id": "work-headless-c36fddb388d8599d9f5e70e40296eae13ccfa8ddaccf3976daacfa18e2ce373e",
  "execution_count": 1,
  "final_result": "AUTOMATION_COMPLETED_HUMAN_ACCEPTANCE_PENDING",
  "validation_results": "PASSED",
  "closure": {
    "disposition": "AWAITING_HUMAN_ACCEPTANCE",
    "human_acceptance": null,
    "human_acceptance_required": true
  }
}

Inspect the receipt and closure for the same Work, then give the result to the named reviewer. PASSED is the recorded validation result; AUTOMATION_COMPLETED_HUMAN_ACCEPTANCE_PENDING means automated completion with human review outstanding. Do not turn that into accepted, production-validated or customer-deployed. A missing report or a different outcome requires its own recorded explanation before continuing.

Read the corresponding actual result in the step-by-step reader.

07 · Open the returned JSON and PDF

1. Read selected_report.json_path and selected_report.pdf_path in your own show response. Use those exact paths with your authorized local viewer, or ask the operator for an approved copy. Private lab paths are intentionally omitted here.
2. Confirm both files exist and are readable. Compare their Work ID/revision with the selected report. A path returned by the service alone does not establish delivery to your computer.
3. For byte verification, compare the JSON file SHA-256 with selected_report.projection.json_file_sha256 and the PDF file SHA-256 with selected_report.projection.pdf_sha256, accounting for the latter’s sha256: prefix. Use the file verifier supplied for your platform.

Actual local R234 projection fields, other fields omitted:

{
  "json_file_sha256": "d7c014b72ebb839269c0ab11c0c23bea7e07416178ec31583b7d10b6bc0ef996",
  "pdf_sha256": "sha256:1265657f5b51e8e63dd86a3977a91731f4f6893b37e1f1431a6977d88ddbb4f3",
  "report_sha256": "sha256:f97ee5c9726fd67e47343eb7425e56af11ad74f56a77e38636311a335ec0fc48"
}

The two file hashes differ from report_sha256, which identifies the report digest and is not the raw JSON/PDF file checksum. Your run produces its own values. These are report artifacts; any separate underlying operation output needs its supported artifact handoff. Keep the raw reports private and share only the approved minimum. Completion here means matched, readable reports and explicit pending human acceptance.

In this exercise, the physical JSON and PDF file hashes matched the returned projection, and the JSON matched the selected report. The PDF was subsequently rendered in the native viewer. No separate generated output file is claimed.

macOS file check

Replace both placeholders with the returned paths. This prints a checksum beside each file; compare the numbers with the projection fields above. Open the PDF through File → Open in Preview and confirm the Work, execution count and validation on its first page.

REPORT_JSON="PASTE_EXACT_selected_report.json_path"
REPORT_PDF="PASTE_EXACT_selected_report.pdf_path"
shasum -a 256 "$REPORT_JSON" "$REPORT_PDF"

Read the corresponding actual result in the step-by-step reader.

08 · Understand the observed input error and correction

Before the successful run, the older instruction used “Create a local lineage artifact for this approved operator exercise”. It omitted the required audit term. The response was PACKR_OPERATOR_STATUS_UNAVAILABLE with nested PACKR_IPC_MALFORMED_REQUEST and SEMANTIC_INTENT_TYPE_UNRESOLVED. Read the nested reason; this error did not by itself establish a service outage.

1. The operator preserved the failed response and queried work list under the same account and installation.
2. That query returned empty works, admissions, executions, reports, receipts and closures. No plan or Work execution was reached. A local session record could already have changed, so this was not a zero-mutation claim.
3. After the supported input requirement was verified, one corrected invocation used create audit artifact. It produced the Work reviewed in steps 4–7; it was not a retry of an existing Work.

Do not reproduce the bad text as a test or build an automatic correction loop. On timeout or uncertain completion, reconcile first; an empty scoped list alone is not universal proof that no Work exists. If an existing Work is found, inspect it rather than resubmit. Preserve attempt history. After review, service shutdown belongs to the operator and the supplied procedure; stop only a service you are authorized to stop.

The following sections retain the deeper command reference. The earlier disconnected capture describes a separate observation, not the outcome of this successful local exercise.

After evidence collection, the operator stopped only this exercise’s service and retained its runtime state. Reopening this completed lab’s endpoint requires a separately authorized start; the earlier recorded RUNNING value is not a current live-status promise.

A separate read-only syntax correction

An actual help invocation with --json --hepl returned exit 2, PACKR_OPERATOR_INVALID_ARGUMENT and an unknown-option reason. Correcting it to --help returned exit 0 and listed supported commands. This parser-only check made no service request or state change. Keep it separate from the rejected Work preparation above, which could record session metadata. Fix the option spelling; do not restart the service or submit Work for this error.

Read the corresponding actual result in the step-by-step reader.

09 · Reference — Start with the installed appliance

Headless is VibePackr operation without keeping PackrGUI open. Use packrctl for local health, status and registered Work. The product service owns execution and records; closing a desktop window does not prove that the service stopped.

1. Confirm the delivered release, the approved appliance, installation identity and operator account.
2. Confirm the installed client can reach that installation’s local endpoint. Use the supplied endpoint, not a path copied from another machine.
3. Obtain the installation’s supported configuration and permitted operation scope before submitting Work.

Release boundary: r232 has bounded first-boot and one low-risk Headless Work evidence. Its fresh-customer administration path remains blocked at initial Admin setup (C7). These commands do not install the appliance or establish an administrator. A complete customer installation procedure is not established by this guide.

For desktop monitoring see PackrGUI; service lifecycle and administrator setup prerequisites are in VibePackr Admin.

Collect your operating handoff

Ask the delivery contact for the following customer-facing handoff. The accountable roles below are responsibilities to assign in your organization, not additional product roles.

If the supported administrator handoff is missing at the r232 C7 boundary, return that exact missing item to the delivery contact. Do not create credentials or grants from this checklist.

Choose the complete operating route

Use a terminal on the appliance or the explicitly supplied local client environment, signed in as its assigned operator. A terminal on your desktop does not automatically address a remote appliance. The socket command below selects a local endpoint; it does not establish an SSH or remote administration connection.

Start at the usage workflow hub when choosing between desktop work, asset browsing and administration.

10 · Reference — Connect and take a baseline

Run these commands as the installation’s authorized local operator. They inspect the existing service; they do not start it.

packrctl --help
packrctl status
packrctl health
packrctl status --json

If the installation specifies a non-default local socket, supply its absolute path:

packrctl --socket /ABSOLUTE/INSTALLATION/control-plane.sock status --json

The path above is a placeholder. --timeout-seconds accepts 1–300 seconds; the default is 90. A longer timeout changes how long the client waits, not whether execution is allowed. Preserve the command, time, exit code and returned reason when a query fails.

11 · Reference — Read health and readiness separately

status shows Service, Readiness, Authority, ETS, Packtory, Runtime, Work counts, Last Receipt and Snapshot Revision. health separates Liveness, Core Readiness, General Work and Product Asset Work. Inspect the component reason as well as its state.

Mini scenario: a running service with General Work ready and Product Asset Work not ready calls for checking Packtory/ETS bindings for asset-dependent Work. It does not establish a need to reinstall the service. This is an interpretation example, not captured output.

12 · Reference — Read the observed local health failure

Earlier disconnected observation · 4 October 2026. The MacBook local R234 candidate previously returned a connection-refused response. This retained observation used the existing default endpoint; it is separate from the isolated installation and successful Work described above.

A read-only health --json query with the matching local CLI returned the following observations. This is a textual record of actual CLI output, not a terminal screenshot or a successful health example. The private endpoint path is omitted from this public summary.

Keep the exit code and error together. Ask the installation operator to check the supplied endpoint and intended service. This observation does not authorize starting, recovering or replacing existing state. The new local R234 CLI walkthrough above separately records a successful Work and result readback.

13 · Reference — Use health checks in automation

packrctl health --quiet
packrctl health --json

Run these as separate alternatives. --quiet is supported only by health and cannot be combined with --json. Quiet mode suppresses the normal health display; retain errors and the exit status.

Do not write an automation rule that turns every nonzero exit into restart. Route an authorization failure to access review and a readiness failure to the named component.

Task 1 — Decide whether to proceed with a planned check

Input: the appliance operator has supplied the local account and endpoint. Goal: record a readiness decision without changing the service. In a POSIX shell, run the following one-shot example. It uses the configured default endpoint; add the previously verified socket option if your handoff requires it.

#!/bin/sh
packrctl health --quiet
health_exit=$?
case "$health_exit" in
  0) printf '%s\n' 'Health ready; review operation authorization separately.' ;;
  1) printf '%s\n' 'Not ready: inspect packrctl health --json and component reasons.' ;;
  2) printf '%s\n' 'Check invocation arguments before another query.' ;;
  3) printf '%s\n' 'Ask the appliance operator to check endpoint and service.' ;;
  4) printf '%s\n' 'Ask the administrator to review the operator binding.' ;;
  *) printf '%s\n' 'Unexpected exit: retain the literal error for support.' ;;
esac
exit "$health_exit"

1. Retain the error text and original exit code. The example deliberately has no retry, restart or Work submission.
2. For exit 1, run the separate JSON health query above and identify the first non-ready component and its reason. For exit 3, give the operator the endpoint and error. For exit 4, give the administrator the binding context without credentials.
3. After the responsible owner resolves the stated cause, run the health query once more and compare the same component. Complete this task when the exit code and component reason are recorded; proceed to Work only when its readiness and authority requirements both hold.

14 · Reference — Find and inspect your Work

packrctl work list --limit 10 --json
packrctl work show WORK_ID --json

Replace WORK_ID with an identifier returned for your own Work. List defaults to 25 and accepts 1–100; results are sorted by most recent update. The local query is scoped to the same authenticated installation/local principal, so an empty list does not establish that the appliance has no Work.

These r232 commands return structured JSON, including without --json. List includes works, admissions, executions, receipts, closures, reports and canonical_revision. Show includes the selected work, invocation, reports and selected_report. Correlate records by Work ID; do not join records merely because they were displayed together.

Selection and result corner cases

15 · Reference — Run one registered low-risk operation

This command creates Work and a local artifact. Use it only after installation readiness and the operation’s authorization are established. It demonstrates the registered CREATE_AUDIT_ARTIFACT operation, which creates a structured local lineage artifact; it does not audit arbitrary attached content.

packrctl work run CREATE_AUDIT_ARTIFACT "create audit artifact" "REPLACE_WITH_UNIQUE_APPROVED_KEY" --json

1. Choose an approved, non-confidential intent and a new key for this one intentional run. Replace the key placeholder.
2. Submit once. Preserve the returned prepared_plan and result.
3. Read the returned Work identifier and inspect it with work show.
4. Review the report outcome, validation and receipt before treating the result as complete.

The run helper prepares and executes in one invocation. It is not an arbitrary shell, general AI prompt runner or file-audit command. A timeout is not permission to run it again. Exact replay requires the same prepared envelope; re-running the convenience command may prepare a different plan and conflict with the existing key.

Task 2 — Follow one Work from submission to review

Inputs: use the operating handoff above. The intent in the command is the supported wording used in the local R234 exercise. The Work owner must replace the key placeholder with an unused approved key for this actual exercise. The steps below all concern the single Work returned by that submission.

1. Run the baseline health/status commands; record the installation and readiness. Stop before submission if the required component or authorization is unresolved.
2. Run the CREATE_AUDIT_ARTIFACT command above once. Find the returned result.work.work_id. Keep that exact value with the key; do not infer the ID from your intent text.
3. Run packrctl work list --limit 10 --json. Locate the same work_id in works; if absent, check the account/scope and recent-list limit. Do not submit a replacement Work to make it appear.
4. Run packrctl work show WORK_ID --json, replacing the placeholder with that exact ID. Compare work.work_id and reports[].work_id with your saved ID. Continue to the report-reading example in the next section.
5. If submission timed out, follow the interrupted-response branch there before any new submission. If show is denied, the administrator checks the original account/installation scope. Never switch accounts to bypass that denial.

16 · Reference — Interpret completion and interrupted work

Read result.work, reports[].final_result, replayed and canonical_revision. A report reference or process exit alone is insufficient.

Interrupted-response scenario: retain the key and request context, list your Work, then show the matching Work. Review its report and effect before deciding the next action. If the exact result cannot be reconciled, stop submission and provide the sanitized identifiers to support.

Read the selected report and its artifacts

Synthetic reading excerpt: the invented identifier and selected fields below illustrate the show response. This is a partial excerpt, not a complete response, captured run or schema-validation fixture.

{
  "work": {
    "work_id": "work-headless-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "state": "AWAITING_HUMAN_ACCEPTANCE"
  },
  "selected_report": {
    "canonical_report": {
      "work_id": "work-headless-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "final_result": "AUTOMATION_COMPLETED_HUMAN_ACCEPTANCE_PENDING",
      "validation_results": "PASSED",
      "closure": {
        "human_acceptance_required": true,
        "human_acceptance": null
      }
    }
  }
}

1. In the actual selected_report.canonical_report, compare the Work ID, final_result, validation_results, receipt and closure. In the example, validation passed but human acceptance remains pending. Assign that review to the named Work reviewer.
2. Inspect selected_report.projection and the returned selected_report.json_path / selected_report.pdf_path. The JSON is the canonical report; the PDF is its reading projection. Use the exact returned paths with your authorized local viewer or request approved copies from the appliance operator. Do not invent a storage directory or assume a returned path proves a file was delivered.
3. Read the JSON/PDF report artifacts for the same Work and revision. Record the report reference and selected_report.canonical_report.report_sha256; an unreadable/missing artifact goes to the operator with that reference. The command has no separate report-download verb in this guide. Obtaining the operation’s underlying output, beyond these report artifacts, requires the installation’s supported artifact handoff.
4. Completion check: one submission, one matched Work, a readable report and its validation/receipt/closure reviewed, with any human acceptance explicitly pending or separately recorded. A null selected report or missing receipt means stop the completion claim and send the Work ID and literal result to support.

17 · Reference — Check runtime and asset dependencies

packrctl packtory status --json
packrctl ets status --json

Read status, reason_code, binding_configured and the reported counts. A configured binding is not proof of a usable storage or correlation path. ETS reports correlations; Packtory reports recorded assets. Unknown counts remain unknown.

Runtime choices and configuration are separate from the runtime actually bound to a Work. Review requested versus actual selection in the available Work/GUI projection. Where the delivered runtime configuration supports AUTO, PREFER or PIN, keep those choices distinct; a pinned runtime must not be treated as silently replaced. Use the delivered configuration surface, not invented packrctl configuration flags.

Continue with Packtory Admin for asset administration and PackrGUI for the available projections.

Check only the dependency your Work needs

1. The Work owner identifies whether the intended operation requires Packtory assets or ETS correlation. From the same local operator terminal, run the corresponding status command above.
2. Read the binding flag together with status and reason. If the binding is not configured, ask the installation administrator for the supported binding handoff for this installation; this guide provides no configuration command.
3. If configured but not ready, give the component owner its reason, target and observation time. A zero recorded count alone cannot distinguish an empty ready inventory from an unavailable projection.
4. After the owner resolves the prerequisite, repeat that read-only query and then health. Completion means the relevant dependency is understood and its required readiness is recorded; it does not claim new assets or correlations were created.

18 · Reference — Diagnose before changing service state

After any authorized service repair, repeat status and health, then inspect the original Work. Update/rollback and recovery belong to VibePackr Admin. For support, retain release, command, time, exit, component reason and sanitized Work/report references. Exclude credentials, confidential intent, raw payloads and unrestricted logs. See Troubleshooting.