HX-AEIR Getting Started¶

Deploy, initialize, connect, and complete the first evidence workflow.

Reference PDF: Marketplace deployment reference, v1.0, published August 26, 2026. Marketplace distribution is planned; use the current private-distribution instructions below. Audience: cloud administrators, security engineers, evaluation teams, and reviewers.

Distribution and validation boundary

This guide documents the validated customer-project behavior of HX-AEIR 1.0.1. Private cross-project image validation does not establish Google Cloud Marketplace approval, a product license, Marketplace-owned image-copy validation, or Producer Portal acceptance. Deploy only through a distribution path explicitly authorized for your organization.

Product at a glance¶

HX-AEIR (Agent Evaluation Incident Reconstruction) is a single-tenant virtual appliance for reconstructing AI-agent evaluation incidents and near misses from customer-supplied records and evidence. It binds authorization, measured environment state, tool and network activity, human approvals, response actions, remediation, and disclosure lineage into portable, cryptographically verifiable evidence packages.

Core boundary

HX-AEIR preserves and independently verifies the evidence chain. It does not host or control an AI model, perform inference, monitor behavior, enforce runtime policy, or provide prevention or containment.

HX-AEIR does	HX-AEIR does not
Validate and bind customer-supplied evidence	Poll, execute, or directly integrate with an AI model
Preserve declared and effective control states	Operate a sandbox, firewall, identity system, or policy engine
Issue incident, near-miss, closure, and disclosure records	Prove that source-system claims are factually correct
Export packages for independent offline verification	Guarantee evidence completeness or absence of unobserved harm

Obtain the current release¶

HX-AEIR is available through Private Appliance or a scoped pilot. Request HX-AEIR access to establish the authorized distribution and evaluation scope. Google Cloud Marketplace distribution is planned.

Before deployment, obtain the release identifier, qualified image reference, reviewed Terraform package, release-bundle digest, and matching operating and verification instructions through your agreed delivery channel. Confirm the destination Google Cloud project is authorized to use that image. Existing evaluators who are missing these materials should use product support.

Deploy the supplied package using Deploy the appliance, then continue with Authorized initialization and mTLS below. Access to an image or to this guide does not itself grant a license or authorize initialization.

Reference deployment¶

Customer access (IAP/OS Login or approved HTTPS ingress) → Nginx mTLS (TCP/443 termination) → HX-AEIR (Unix socket; unprivileged app) → Local custody (evidence store + ML-DSA-65 key) → Portable output (evidence package + pinned public key).

Reference element	Default or boundary
Deployment model	Customer-project private VM appliance; Marketplace Pattern 1 is the planned distribution model
Compute reference	One Shielded Compute Engine VM; `e2-standard-2` reference profile (2 vCPU, 8 GB memory)
Storage reference	One 50 GiB `pd-balanced` persistent boot/data disk
Availability	Single-zone, single-VM reference deployment; no automatic zonal failover
External IPv4	Disabled by default; optional when the customer selects public ingress
Application path	Nginx mTLS on TCP/443 → Unix domain socket → unprivileged HX-AEIR application
Administrative path	IAP TCP forwarding → TCP/22 → sshd with OS Login
Partner runtime	None. Marketplace distribution and support processes are outside the workload runtime

Prerequisites¶

A customer Google Cloud project with billing enabled, authorized access to the supplied image and deployment package, and permission to create the required resources. Marketplace entitlement is required only when using that distribution route.
A customer-selected VPC and subnet in a supported zone.
IAP TCP forwarding and OS Login enabled when the recommended administration path is used.
Customer IAM assignments for deployment, IAP tunnel access, and OS Login as appropriate.
Customer-managed server TLS material, client CA, and one or more client certificates for mTLS.
Approved CIDR sources for TCP/443 when public ingress is selected, or customer-provided private connectivity for private ingress.
A named owner for evidence retention, backup, recovery objectives, and public-key pinning.
A defined first use case: evaluation authorization, preflight, incident or near miss, closure/remediation, or disclosure derivative.

Do not place secrets in the deployment inputs

Do not paste private signing keys, client private keys, credentials, regulated data, or confidential evidence into Marketplace metadata or general support forms.

Deploy from Google Cloud Marketplace when available¶

This procedure applies only after HolonomiX supplies an active listing for your authorized release and you confirm entitlement in your own project. For current Private Appliance or pilot delivery, use the supplied package as described above.

Open the HX-AEIR listing and select the deployment option.
Choose the destination customer project, supported zone, VPC, and subnet.
Use the qualified machine profile. The reference configuration is e2-standard-2 with a 50 GiB pd-balanced disk.
Leave the external IPv4 option disabled unless the approved customer design requires public ingress. If enabled, restrict TCP/443 to approved customer CIDRs.
Enable optional customer-supplied CMEK only for persistent-disk encryption. CMEK is not the HX-AEIR application signing key.
Review the service account and IAM behavior. The deployment module does not grant broad project IAM roles to the attached VM identity.
Deploy and wait for the VM and startup configuration to complete.
Record the deployment name, project, zone, internal IP, selected ingress mode, and operational owner.

Marketplace image posture

The qualified appliance image is neutral and does not contain a customer signing key. The customer-local ML-DSA-65 signing identity is created during authorized initialization after deployment.

For command-level deployment, initialization, API, backup, upgrade, and uninstall reference, see Deployment on Google Cloud.

Authorized initialization and mTLS¶

Connect through the administration path¶

Use customer-authorized IAP TCP forwarding and OS Login to reach TCP/22. The SSH administration path is independent from the application path; Nginx does not proxy SSH.

Verify service readiness¶

Confirm the HX-AEIR service is running under the unprivileged application identity.
Confirm Nginx is bound to TCP/443 and the application is reachable only through the local Unix domain socket.
Confirm the health response reports that runtime prevention by HX-AEIR is not performed.
Confirm the persistent disk is mounted and has sufficient free capacity before initialization.

Initialize the customer signing identity¶

Authorize initialization under the customer change-control process.
Generate the customer-local ML-DSA-65 keypair using the appliance initialization workflow.
Confirm the private key remains local to the appliance and is not included in exports, logs, or support bundles.
Export or retrieve the public key through the documented public-key path.
Record the public-key fingerprint in an independent customer system for later pinning and verification.

Configure client mTLS¶

Install the customer-managed server certificate and private key for Nginx.
Install the client CA used to validate authorized API clients.
Issue client certificates according to the customer PKI and access policy.
Restrict TCP/443 at the firewall to the selected ingress sources.
Test a health request using an authorized client certificate before submitting evidence.

Complete the first evidence workflow¶

Authorize (define allowed scope and controls) → Preflight (capture effective environment state) → Record (submit incident or near-miss evidence) → Close (link remediation or closure revision) → Export (create portable evidence package).

Create or ingest the evaluation authorization record. Bind the agent/model identity, harness, allowed tools, network policy, approval requirements, targets, and stop conditions.
Create or ingest an independent preflight result. Record the effective network, identity, credential, tool, and safeguard state before launch.
Submit the runtime evidence set. Include only customer-approved records and normalized references; do not embed raw secrets.
Create the incident or near-miss record. Separate declared state from effective state and label claims as observed, reported, derived, or unknown.
Create a closure or remediation revision when actions are completed. Preserve the prior receipt digest; never overwrite the earlier record.
Export the evidence package and the independently pinned public key for review.

Evidence interpretation

A valid signature proves integrity and issuer-key verification for the signed material. It does not establish that every source claim is true, that telemetry is complete, or that no unobserved harm occurred.

Export and verify¶

Export the package through the HX-AEIR customer-controlled export path.
Transfer the package and the pinned public key to a separate customer-operated verification host.
Run the standalone offline verifier without network access to the appliance or HolonomiX.
Review receipt integrity, schema validity, profile bindings, evidence manifest, linked receipts, trace root, evidence artifacts, revision linkage, and disclosure linkage.
Retain the verification report with the reviewed package and public-key fingerprint.
Optionally duplicate the package, alter a signed field, and verify that the tampered copy is rejected.

Typical status	Meaning
`VALID`	The package, signature, schema, commitments, and required links verify under the pinned public key
`PARTIAL`	The package verifies, but completeness or materialization is bounded by declared coverage or missing optional source material
`REQUIRES AUTHORIZED SOURCE PACKAGE`	A public disclosure commitment verifies, but full source reconciliation requires the separately controlled source package
`INVALID`	A signature, digest, link, schema rule, trace root, or package integrity check failed

Operate and troubleshoot¶

Symptom	Check first	Resolution path
IAP/SSH access fails	IAM, IAP API, OS Login, TCP/22 rule	Correct the customer access prerequisites; do not route SSH through Nginx
mTLS request fails	Client certificate, CA chain, server name, TCP/443 source	Correct customer PKI material or firewall source restrictions
Health fails	Service state, Nginx, Unix socket, disk capacity	Restore the service/socket dependency and inspect local logs
Signature verification fails	Pinned public key, package integrity, receipt digest	Confirm the correct issuer key and reject altered material
Linkage is incomplete	Authorization, preflight, prior revision, disclosure source	Supply the authorized linked package or treat the result as incomplete
Disk capacity is low	Evidence retention and export policy	Export and retain evidence under customer policy; expand or rotate storage

Back up the application state and signing-key material only under an approved customer recovery process.
Test restore before relying on backup as an operational control.
Preserve the public key and historical evidence before upgrade, rollback, or decommissioning.
Do not send signing secrets, credentials, or confidential evidence through a general support channel.

Support and references¶

HolonomiX provides direct support for authorized deployment, initialization, mTLS configuration, evidence submission, package export, offline verification, backup and restore, upgrade, rollback, and decommissioning guidance. Scope and response commitments are governed by the applicable order or agreement; Marketplace terms apply when that distribution route is used.

Support: holonomx.com/support
Security: holonomx.com/security

References: Google Cloud Marketplace, offering VM products · IAP TCP forwarding · OS Login · NIST FIPS 204