Client installation, connection and agent setup

The server commands below require a verified server release that supplies the native setup entry. The copied reference listing alone cannot install or configure an appliance. Confirm the administrator-provided path before using /opt/vibepackr/setup.

1 · Separate server and client responsibilities

The administrator runs install.sh on the Linux VM to install the server release. setup.sh is the server entry point for initial configuration and later approved changes. An administrator using Windows, macOS or Linux connects to the same VM by SSH and runs the same Linux commands there. Desktop client installation uses the OS package instead.

ssh ADMIN@VM_HOST
# Run the following on the intended Linux VM, from the verified server package:
sha256sum -c SHA256SUMS
sudo sh ./install.sh
# After installation, inspect the available setup commands:
/opt/vibepackr/setup --help

Replace ADMIN and VM_HOST with organization-provided values. Run install.sh only for the intended server installation; adding a new legacy system or model does not require reinstalling the VM. Use the native administrative operation selected by setup.sh and the VM administrator guide. Do not run the server installer on a workstation.

2 · Verify and install the matching OS package

Obtain the installer and its authenticated release inventory from your administrator. Compare OS, CPU, release and SHA-256 before opening it. A checksum detects changed bytes; verify its trusted source separately. Keep the working installation and organization profiles until the new release is checked.

Verification examples below use a placeholder installer name. Substitute the actual supplied filename and compare with the exact release inventory.

Get-FileHash -Algorithm SHA256 -LiteralPath ".\CLIENT_INSTALLER.msi"

shasum -a 256 ./CLIENT_INSTALLER.dmg

sha256sum ./CLIENT_INSTALLER.deb
# On the supported Debian workstation:
sudo apt install ./CLIENT_INSTALLER.deb

A closed network needs approved native OS prerequisites in advance; the optional SDK Rust/crate package does not supply WebView2, GTK or WebKit. Do not disable package-signature or OS trust checks to force installation. If macOS policy requires Developer ID/notarization, obtain an approved distribution path from IT; a DMG alone does not establish Apple trust.

3 · Open the installed manuals before launching a tool

• Windows: open VibePackr Manual from the installed Start-menu folder, or open Manuals/Start_Setup.html inside the actual installed release.
• macOS: open Open Manual.command in the copied VibePackr Client folder, or double-click Manuals/Start_Setup.html. Do not keep reading a copy inside the mounted DMG after ejecting it.
• Linux: open VibePackr Manual from the desktop application menu, or open Manuals/Start_Setup.html below the installed /opt/vibepackr-client release. A graphical browser is required only for viewing HTML.
• Start_Setup opens Part.1. Series index opens Parts 1–8 and this guide. EN is the default; KR switches the text while keeping command identifiers and English SVGs. Relative links continue to work without a network.
• If code Copy is unavailable under local browser policy, select the code text and copy manually. The command/type header remains visible. Make editable example copies in a new user results folder; never edit the installed example in place.

Run the following customer-access examples only when your administrator has supplied the matching native client and private configuration. These executables are not included in this documentation ZIP. Replace issued_at: 0 with a fresh approved timestamp; the example is deliberately incomplete.

4 · Check the intended appliance connection

Your administrator provides the expected appliance/organization identity, compatible release, private endpoint and TLS server name, plus your own device certificate/key references. Shared installers contain no customer endpoint or private key. Keep credentials outside Manuals, example inputs and agent prompts.

PackrGUI and Builder display native state through their configured product connection. Do not treat the Settings local AI endpoint as an appliance mTLS endpoint. Use the supplied customer-access client and its private configuration for the supported remote protocol; follow the administrator-provided GUI connection procedure for that release.

Example: ask the setup agent to create a fresh HEALTH request with the current Unix time and the private client configuration described in the supplied Customer access guide. Run the matching installed native binary. The timestamp below is a placeholder, not a reusable request.

{
  "protocol_version": "PACKR_CUSTOMER_ACCESS_V1",
  "request_id": "client-health-01",
  "issued_at": 0,
  "operation": {"type": "HEALTH"}
}

./bin/packr-customer-access-client \
  --config /absolute/private/customer-access-client.json \
  --request-file /absolute/private/client-health.json

& ".\bin\packr-customer-access-client.exe" `
  --config "C:\PRIVATE\customer-access-client.json" `
  --request-file "C:\PRIVATE\client-health.json"

Expected ready response fields: SUCCESS, READY, CUSTOMER_ACCESS_READY, transport_is_authority:false and authority_added:false. This is an expected-output example, not a captured response from your appliance. Confirm the returned installation and allowed role separately. A window opening, health of the local adapter or a copied certificate does not prove authenticated appliance access.

Open the full Skills, MCP and TOML reference

5 · Connect the common Skills, MCP and planning worksheet

Choose where the AI agent actually runs. An agent running only on the Linux VM uses the VM adapter. An agent on Windows, macOS or Linux uses that workstation adapter. One common tool-specific Skill set covers install/setup, headless, PackrGUI, GAPE, Helper, Contract & Document, SDK and Builder. Each application does not require its own copy.

The setup agent creates a new private registration through packr-agent-mcp register, then imports its generic stdio descriptor through the selected AI runtime’s documented mechanism. Import the Skills through that runtime’s supported method as well. Preserve existing runtime settings; ordinary workers do not edit the kit. runtime-plan.example.toml is a planning worksheet and must not be loaded as an executable connection configuration.

./bin/packr-agent-mcp --version
./bin/packr-agent-mcp register /absolute/private/setup-request.json

Registration creates registration.json, mcp-server.json and SETUP_RECEIPT.json in a new private output directory. It does not automatically modify the AI host, prove Skill loading or authorize Work. The administrator verifies initialize/initialized, tools/list with 13 expected tool IDs, vibepackr.setup.status and the actual Skills the host read. See Skill.html and the included agent kit MCP_SETUP.md for schema fields and recovery examples.

The MCP adapter has a limited native tool set: setup status, read-only headless queries, GAPE validation/comparison, SDK analysis and Helper operations. GAPE capture, SDK generation, Builder UI, server installation and actual binding use their supplied public tool paths and Skills. The local stdio adapter is not an automatic remote tunnel to the VM.

Part.8 · Recovery and post-install expansion

6 · Add another legacy system, runtime or model after installation

• Preserve the working installation, current bindings and unfinished Work. Record the existing release and an approved before-state observation; choose a new results folder.
• Run GAPE again for the changed supported source revision. Validate and compare the before/after snapshots; a worksheet or stale snapshot is not a new observation.
• Use Helper before declarations to assess gaps and risks; update Contract & Document declarations; then repeat the affected Helper validation/prepare checks.
• Reuse a compatible implementation or approved Pack when it meets the goal. Invoke SDK only when a new supported adapter is needed, and Builder when a new Pack candidate is needed. Preserve candidates separately from approved Packs.
• Apply the approved native server setup/binding operation, verify actual connection and affected old workflows, and retain a rollback disposition. Do not infer execution authority from a candidate or successful registration.

An interrupted operation is reconciled against its original operation reference and native record before any repeat. A changed target, input or catalog uses a fresh reviewed registration. A new request ID alone is not a recovery procedure.

7 · Concrete failures and recovery

8 · Keep a useful installation and connection record

Record the release/installer digest, OS/CPU, actual install and manual paths, native version, expected installation identity, redacted connection result, observed MCP tools/Skills and any unresolved reason code. Keep private connection files and certificates outside shared support records. Confirm an ordinary read-only example before requesting Work execution.