Part.7 · PackrGUI and headless operation

Use case 3: Verify PackrGUI and headless routes separately

First connection exercise: separate general users from VM administrators

Goal: connect your client to an already prepared company VM and confirm matching customer/installation identity. This exercise does not automatically execute Work. If no company VM exists, the deployment owner follows installation sections 1–4; general users receive the installation identity, readiness and connection material.

1. Material to obtain from the administrator

Obtain the actual compatible client file, digest/signature status, customer/installation/release references, endpoint and TLS server name, account/device enrollment method, allowed role and enrollment expiry/renewal support route. Receive any per-device profile through the organization's secure channel. Do not paste private keys into documentation or place them in a common installer ZIP. Use automatic enrollment portals only when the release actually provides one.

2. OS-specific preparation and launch location

If the app cannot open, record an application launch problem, before server connection. Check the exact OS warning, app path/version/CPU and included files. Disabling OS protections or running as administrator is not a general remedy.

3. Connect, enroll and confirm identity

1. Open the app and use the release's connection/profile procedure. Compare the supplied endpoint, TLS server name and profile; do not guess a new server.
2. Complete the release's supported user/device enrollment. OS login, browser return or selecting a profile does not establish completed enrollment. Report expired or unregistered state to the administrator.
3. Compare displayed customer/installation/release identity with the administrator's expected values. Record authentication and server readiness separately. Stop if another organization/installation appears.
4. Begin with a status query. If no permitted Work is available, ask the administrator to check the current role/entitlement. General users do not need VM administrator login.
5. Only users who need headless operation separately query authentication through that release's CLI/service profile. Do not copy GUI credentials arbitrarily or mark headless complete from GUI success.

Expected result: record the launched client's version/path, matching customer/installation reference and actual authentication state. If user enrollment or operational connection is not yet validated for that candidate, retain it as unconfirmed; do not fill in an assumed successful screen.

If blocked: launch problem → package/OS preparation; timeout/authentication → case C; changed identity → case B; admin enrollment → D/E. Follow the separate first Work use case for actual execution.

Operational goal

A customer connects from a workstation GUI and, if operational automation is required, checks the release-provided headless route separately. Even against the same appliance, the routes can differ in installer, authentication, session, allowed functions, and result evidence.

Example situation

An operator sees the status screen in PackrGUI on a Mac. The team says, “Then headless Work on our Linux server is ready too.” That conclusion is unverified. Each client must directly prove authentication, installation identity, and permitted function.

Route-specific checklist

Carry out the checks

1. Compare each platform's exact installer with the release manifest. A successful Mac package does not authorize a Windows package.
2. In the GUI, separately confirm service response, completed authentication, customer and installation IDs, and current permitted functions. An open window is not authenticated status.
3. If headless is in the release, follow its own official authentication, connection, and scope procedure. Do not copy GUI credentials into it on your own.
4. Compare the installation seen by both routes, but do not assume their sessions or permissions are equivalent.
5. For actual Work, confirm final state and receipt on the route that performed it. Record each route separately.

Headless read-only check when this release supplies packrctl

After the installation operator supplies the approved local access route, use these commands if packrctl is included with your installation. Run them on the authorized appliance or managed client. They read status and health; they do not authenticate a GUI session or authorize Work.

packrctl status --json > headless-status.json
packrctl health --json > headless-health.json

Read the JSON readiness and reason fields as well as the exit status. UNKNOWN is not READY. If packrctl is absent from the exact delivery inventory, record the headless route as not supplied rather than reusing a development binary.

Failure branch

If one route fails, use the connection and auth case before copying settings from the successful one. A host-identity warning requires an immediate stop under the identity case.

Completion condition

Record each route as verified only after its installer, connection, authentication, installation ID, and intended function have been checked directly.

Check what your release supplies

For each platform, confirm the installer name, signature, supported version, and connection method in the supplied component list. After installation, record the server identity, authenticated session, and matching customer and installation IDs. If a platform installer or headless client is absent from the list, ask your supplier for the supported option before using another package.

Detailed scenario: only the GUI connects

Suppose PackrGUI on a Mac displays the expected installation ID, while a server automation client cannot connect. The GUI account, token lifetime, and network route may differ from those of the service. A GUI screenshot is not headless authentication proof. First verify that the release includes a headless client; if so, record that route's account, endpoint, and refusal separately.

Conversely, a successful headless status query does not prove that a GUI session exists or has the same authority. Record the last proven stage for each route, such as GUI: authenticated, installation matched and headless: network reachable only.

Platform validation worksheet

Write unverified until a route is exercised. Do not copy success between operating systems or clients.

A concrete operational walkthrough

Suppose the desktop GUI works while scheduled automation is refused. Compare the GUI session and automation service execution location, account, network route and installation scope separately. Use the release service-authentication procedure instead of copying GUI tokens or keys into automation.

Records to reconcile before closing this use case

Retain separate rows for GUI/headless package, version, authentication, installation ID, permitted features and status result. Record an unavailable route as unavailable; bind actual Work receipts to the route used.

Keep the planned procedure, performed actions, observed results and remaining stages separate. This scenario explains the procedure; the documentation update does not execute it in a customer environment.

Back to use-case index

Use case 2: Automatic rebinding after a local runtime change

Operational goal and prerequisites

Within the already approved installation and runtime scope, a local model alias or observed runtime value changes. Core validates the fresh observation and updates the binding. First capture the current installation identity, administrator scope, supported model, and prior binding state.

Example situation

An operator changes a local model alias. The model server runs, but PackrGUI still shows the prior binding time. “The model responds” does not prove that the new model is bound.

Before and after

Work through the change

1. Record the change and time. Do not delete the old binding or edit internal product storage.
2. Use the release wizard's discovery or re-observation route to confirm the new runtime is found.
3. Check the approved customer, installation, and runtime scope. For an out-of-scope change, request an administrator decision rather than expecting automatic application.
4. Read detected → validated → bound and any refusal reason in order. Do not guess among ambiguous model candidates.
5. Confirm the new binding's model reference, installation ID, and time follow the change. Only then record rebinding.
6. Run and validate actual Work and its receipt separately. See the missing-receipt case.

Failure branches and support evidence

If nothing is detected, inspect runtime startup and the official connection route. If validation is refused, use the binding case to separate scope, identity, and ambiguity. In support requests, send before/after state and time, installation ID, and product refusal; omit internal storage and customer prompts.

Completion condition

A fresh observation and new Core binding for this change must be recorded under the same installation identity. This does not establish a Work result or macOS and Windows auto-binding validation.

Detailed scenario: only the model alias changed

Assume a local alias changes from model-A to model-B at 10:00. A bound record at 09:40 belongs to the earlier state. Compare the change time with a later discovery time, then confirm Core validated the new model reference under the same installation ID and approved scope. If multiple candidates become visible, do not silently choose one.

If no new binding appears, classify the stage: no detection suggests runtime readiness or connection checks; an out-of-scope observation goes to the approval owner; an ambiguous target needs an explicit model choice. A screen that merely repeats an earlier timestamp does not establish a new binding.

Example change record

Times and model names illustrate the procedure, not actual release evidence. Verify subsequent Work through its own record.

A concrete operational walkthrough

During a maintenance window, change one supported model alias or runtime address at a time. Retain supported versions, the binding reference and last state before the change; then compare the fresh observation with the intended value. A successful online check or process restart alone does not establish a new binding.

Records to reconcile before closing this use case

Separate before/after runtime/model references, observation times, validation reason, effective binding and any separately authorized Work. A rollback also requires a newly observed/validated result.

Keep the planned procedure, performed actions, observed results and remaining stages separate. This scenario explains the procedure; the documentation update does not execute it in a customer environment.

Back to use-case index

Use case 5: Run the first Work and verify result and receipt

Operational goal and starting conditions

A customer runs one supported Pack or release-named test operation through the governed product path and confirms final result and receipt for the same installation and Work ID. Service readiness, authenticated connection, administrator scope, and current runtime binding must be checked first.

Example situation

An operator reports, “Qwen is bound, so the first Work is complete.” The reviewer asks, “Are the Work ID, execution approval, model call, result validation, and receipt tied to the same operation?” If no Work was submitted, the supported state is only runtime readiness.

Stage-by-stage questions

Carry out one operation

1. Select one approved target and review plan and environment. Do not treat a Builder candidate as an approved Pack.
2. Complete the customer's permitted user approval route. Passkey enrollment, browser return, and actual Work approval are separate.
3. After submission, capture the product-recorded Work ID and read approval, start, and execution state for that ID in order.
4. For local AI, confirm a model call linked to this Work, not just a generally responsive model.
5. Bind result validation, failure or rollback status, and final receipt to the same release, installation, and Work ID. Never rewrite failure, stop, or rollback as success.
6. If the receipt is missing, start from the last confirmed step in the missing-receipt case. Do not create records manually.

Conditional CLI example for an authorized installation

If your release supplies packrctl and lists CREATE_AUDIT_ARTIFACT as a supported operation, use this example only after that one Work is approved and the appliance reports the required authority and preconditions. Replace the key with an approved unused value. This operation creates a local audit artifact; it does not inspect an attached customer document or demonstrate a Qwen model call.

packrctl work run CREATE_AUDIT_ARTIFACT "create audit artifact" \
  "REPLACE_WITH_ONE_UNUSED_APPROVED_KEY" --json > work-run.json
# Copy the returned result.work.work_id; do not invent a Work ID.
packrctl work show "PASTE_RETURNED_WORK_ID" --json > work-show.json

Inspect the typed result, final state, validation, receipt reference and human-acceptance state in the returned records. A command exit code or a generated JSON file alone is not a success receipt. Do not reissue work run after an uncertain result; reconcile the original request through the product's supported route.

Support request and completion

For support, provide release, installation and Work IDs, shareable Pack or operation name, last confirmed stage, first error, and receipt status. Do not attach prompts, customer data, or raw results to an ordinary ticket. Complete: successful final state, validated result, and receipt for the same authorized Work are confirmed together.

Detailed scenario: model responds, but no Work receipt exists

Suppose an operator sees a local model respond and reports first Work complete. First check for a Work ID. Without it, even product receipt of a Work request is unproven. With an ID, read approval, start, model call, result validation, and final state separately. A general model response cannot substitute for a call bound to this Work.

For example, after changing a local model alias, the GUI may show a new BOUND state while Work readiness remains UNKNOWN. Record the authority, runtime, and Work readiness shown by your installation and any exact reason code. Do not submit Work until the required state is ready; send those values through the release support route if readiness remains unknown. Use the worksheet below for your own first Work.

One-Work evidence worksheet

Do not treat a failed, stopped, or rolled-back result as successful merely because a record file exists. Report the first missing gate; exclude raw prompts and output from ordinary support requests.

A concrete operational walkthrough

Plan one approved read operation. Immediately before execution check installation, Pack, input, current authority and plan; retain the actual returned Work ID. If a connection issue delays the result, query that same ID instead of starting duplicate Work to obtain a response.

Records to reconcile before closing this use case

Check that terminal state, postcondition validation, result digest, Work record and receipt refer to one execution. Record failure, rollback, waiting and unconfirmed states separately; a standalone model response does not replace the product receipt.

Keep the planned procedure, performed actions, observed results and remaining stages separate. This scenario explains the procedure; the documentation update does not execute it in a customer environment.

Back to use-case index

Use cases: from installation to operation

Choose by task

How to use this collection

Each use case follows situation → prerequisites → steps → failure branches → completion evidence. If several symptoms appear, start at the last proven state. For symptom-specific resolution, use the case index. Include only minimal release, installation, and verbatim error details in support requests; omit customer content and secrets.

Choose a use case by owner and output

Online operation uses approved network/provider routes; closed on-premises operation provisions required installation assets, models and documentation before transfer. This guide fixes neither as the product default. The optional SDK Rust dependency set prepares SDK adapter-build Rust coverage; it does not replace appliance images, model weights, provider credentials or all native OS development tools.

Example support handover: release/component/OS, time and timezone, last confirmed stage, first refusal, performed change, current result and next owner. Keep unconfirmed, refused, waiting, failed and completed states distinct. Exclude secrets and customer content.

Back to installation and first-use guide