# VM administration

## First local runtime administrator setup

After first boot has created the installation and customer binding, an interactive Linux administrator can register the first runtime binding scope from a terminal:

```sh
sudo /opt/vibepackr/current/bin/packr-appliance-admin bootstrap-runtime-admin
```

Read the displayed runtime scope and type `APPLY` to confirm. The installed release manifest, running administrator binary, and appliance identity must match. This is one-time registration for the local installation; it grants appliance observation and management of the `ollama.local` binding scope for one year. The OS password is handled by `sudo`, and the product credential stays in a root-private file. The Core observes local Ollama metadata every 15 seconds and applies only validated changes inside that scope. It never calls an external AI provider as part of observation. A missing, expired, changed, or ambiguous scope requires administrator review. The setup wizard shows the first registration command but cannot verify appliance status without a connected read-only status path.

VM Admin uses the existing `packr.remote-admin.v1` mTLS service and the existing Appliance Admin authority. Network reachability and mTLS authentication identify the caller; they do not grant an Admin capability.

The Rust Core validates server and client configuration, gateway policy, request envelopes, Admin operations, and responses. Internal contract JSON files remain build and validation inputs and are not installed with the customer package.

## Configure and start

Create a complete `packr.remote-admin-server-config.v1` server config. Its gateway policy must bind the exact organization, appliance, and installation IDs; each client certificate digest maps to one actor, credential path, and explicit `allowed_operations` set. All server, replay, state, certificate, and key paths must be absolute.

Materialize one complete generation:

```json
{
  "schema_version": "vibepackr.access-configuration-file-request.v1",
  "destination_root": "/etc/vibepackr/remote-admin",
  "surface": "REMOTE_ADMIN",
  "generation_id": "remote-admin-20260912-01",
  "server_config_source": "/absolute/private/remote-admin-server.json",
  "server_certificate_source": "/absolute/private/server-certificate.der",
  "server_private_key_source": "/absolute/private/server-private-key.der",
  "client_ca_certificate_source": "/absolute/private/client-ca-certificate.der",
  "subject_bindings_source": null
}
```

```sh
sudo /opt/vibepackr/current/bin/packr-customer-access-gateway \
  --materialize-request /absolute/private/vm-admin-request.json
sudo systemctl start vibepackr-remote-admin-gateway.service
sudo /opt/vibepackr/health
```

## Invoke VM Admin

Create a private `packr.remote-admin-client-config.v1` file with the endpoint, TLS server name, absolute DER paths, bounded timeouts, and maximum response size. A gateway health request is:

```json
{
  "protocol_version": "packr.remote-admin.v1",
  "session_id": "vm-admin-session-01",
  "issued_at": 1789142400,
  "command": { "command": "HEALTH" }
}
```

```sh
/opt/vibepackr/current/bin/packr-remote-admin-client \
  --config /absolute/private/remote-admin-client.json \
  --request-file /absolute/private/remote-admin-health.json
```

Health success returns `wire_status: SUCCESS`, response status `HEALTHY`, and reason code `REMOTE_ADMIN_GATEWAY_READY`. Replace the example `issued_at` value with the current Unix time; stale requests are rejected.

An operation request uses command `EXECUTE` with an `AdminOperationRequest`. Its actor, grant, organization, appliance, installation, expected revision, target, policy scope, and requested time must match current canonical Admin state. The operation must appear in the certificate binding's `allowed_operations`. Existing operations include `STATUS`, `UPDATE_CHECK`, `UPDATE_STAGE`, `UPDATE_APPLY`, `ROLLBACK`, `BACKUP_VERIFY`, `RESTORE_VALIDATE`, and `RECOVERY_RECONCILE`; their prerequisite authority and evidence remain required.

If an execution result is uncertain, send `RECONCILE` with the same request ID and session identity. Do not repeat a mutation with a new request ID as a substitute for reconciliation. Replay, stale request, disallowed operation, identity mismatch, invalid grant, or wrong revision returns a typed `REMOTE_ADMIN_*` reason code.

## Rotation, revocation, update, and recovery

Rotate server or client certificates by materializing a new complete generation, restart the gateway, verify health with the new client, then retire the old credential. Revoke a VM Admin client by activating a new gateway policy without its certificate binding. Never edit the active generation or replay store in place.

After an appliance update, confirm the installed release identity and the current Admin state before enabling the listener. Recovery operations remain subject to the canonical Appliance Admin restore/reconciliation rules and exact evidence. Retirement uses `sudo /opt/vibepackr/uninstall ADMIN_STATE_ROOT REQUEST_FILE CREDENTIAL_FILE`; customer-owned credentials and backup material require a separate explicit purge decision.