7. Installation acceptance

Back to overview · Full table of contents · Download full PDF

This chapter answers one question: can the installed environment actually be used. Acceptance has four layers: host-side services are healthy; readiness states are understood; one real business call goes from the caller through the gateway to the model and back, and can be found in the console by request ID; the deny path rejects as expected and the error code can be read. All four layers, plus the record table in section 7.6, must be complete before the environment is handed to the customer to start the POC. The readers are the implementation engineer and the customer acceptor.

The installer's post-install acceptance (section 4.6) only proves that platform base services are usable. It does not mean models, authorization, and the business path are open. Acceptance in this chapter is judged by post-install acceptance result + zenova status + a real business call, not by what a direct hit on an internal port returns.

7.1 Host-side checks

Applies to: the first acceptance after install; also after every upgrade, every deployment-configuration change, and every host reboot.

Prerequisite: signed in to the install host as root; the install has printed complete and post-install acceptance has no blocking items.

Procedure

1. Inspect each service's status and the current version.

# Install host · root · read-only
sudo zenova status

2. Inspect base services that do not start with zenova-. zenova status lists only zenova- services; the ones below must be checked with systemctl separately (an item not deployed by the installer shows the unit as missing, which is expected).

# Install host · root · read-only
systemctl status postgres clickhouse caddy secret-service spicedb --no-pager
systemctl status rustfs --no-pager        # present only when object storage is Bundled object storage

3. Run a full doctor and save the report, then check the exit code.

# Install host · root · write (creates report files only under /root/zenova-install)
sudo zenova doctor --all --save /root/zenova-install/doctor
echo "doctor exit code: $?"

4. File the report and the zenova status output with the handover materials.

# Install host · root · write (creates files only under /root/zenova-install)
sudo zenova status --json > /root/zenova-install/status.json
ls -l /root/zenova-install/doctor* /root/zenova-install/status.json

What you will see

• zenova status: running state of each zenova- service, current version, instances, and any in-progress or last upgrade. Slotted services such as the control plane, background worker, and runtime store show the slot currently taking traffic (for example zenova-control-plane@a). Column names follow the actual output.
• systemctl: every deployed unit shows active (running) and is enabled at boot (enabled).
• zenova doctor --all: lists every check, including passed and skipped items. Failed items carry a stable diagnostic code (such as HOST_…, SVC_…) and a remedy. When the path after --save has no extension, the report is saved as .txt.
• Exit code: 0 when there is no blocking item; 2 when there is a blocking item.

Note: zenova start/stop/restart accept only service names that start with zenova-. postgres, clickhouse, caddy, secret-service, and spicedb are not started or stopped through the zenova command. When a service is not running, look at the logs first (section 8.5); do not restart repeatedly.

Note: to check connectivity to a model or tool address, add --target <URL> for layered DNS → TCP → TLS → HTTP checks. When the report notes "direct connect; may not match production egress", the result does not represent connectivity of the gateway egress.

7.2 Meaning of ports and readiness

Applies to: during acceptance, when you see 503, a column showing Not verified, or a service missing from zenova status. Check this table first, then decide whether to act.

Procedure

1. For a phenomenon in the table below, use the Meaning column to decide whether it is a healthy state.
2. If it is not a healthy state, go back to section 7.1 and locate it with zenova status and zenova doctor.

Listen-port boundaries:

What you will see: Listener boundary in post-install acceptance has passed; from the business network only the business ingress (and a split-out admin ingress) can be reached.

Note: do not judge whether the platform works by curling an internal port. Returns from internal ports depend on tenant, routing, and slot-switch state; 503 is often healthy. Whether it works is judged by the post-install acceptance result, zenova status, and the real business call in section 7.3.

Note: 3010, 3080, 3300, 3320, and 3325 listen on all interfaces so containers on this host can call back. The installer does not block them at the network boundary for you. On the host firewall or cloud security group, open only the ingress ports to the outside.

7.3 A real business call

Applies to: must be completed once before every POC environment is handed over. This is the only direct proof that "installed" means "usable".

Prerequisite: Chapter 6 is done (password change, two-factor, tenant created, license imported); you have a usable upstream model address and credentials; the tenant has a test member account (created under the tenant's Organization & access). Model providers, models, model groups, and availability are operated by the tenant administrator. Platform root has no tenant membership and cannot run a playground call.

Procedure

1. Add a model provider. The tenant administrator opens Admin Console → Models → Model Providers, chooses Add model provider, selects the provider type, checks Request address and Model request format, fills in credentials, clicks Test connection and fetch models, Enables the models needed in the model table, and clicks Save model provider.
2. Playground the model. Open Admin Console → Models → Models, open the Playground tab on the model just enabled, send one sentence, and confirm a success summary is returned.
3. Add a model group. Open Admin Console → Organization & access → Model Groups, create a model group, fill in a name, add the model that just succeeded in the playground, and save.
4. Authorize the test member. On that group's Availability and quotas tab, choose Edit availability, select the test member, set validity to Long-term or covering the POC period, and save.
5. The test member creates an API key. The test member signs in, opens Capability center → Home → API Keys, chooses Create key, fills in a name, selects the model group authorized in the previous step and the billing owner, clicks Confirm, and immediately copies API Key (shown only this time). Administrators do not create keys for members in the console.
6. Make a real call from a host on the business network.

# Host on the business network · ordinary user · write (produces one real call; it is billed)
export API_KEY='<test-member-API-key>'
curl -sS -i "<access-url>/api/v1/agent-gateway/openai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model-name>","messages":[{"role":"user","content":"hello"}],"max_tokens":32}'

7. Record x-request-id from the response headers. An administrator opens the Gateway requests tab under Admin Console → Overview, searches by that request ID, opens the detail, and checks it.
8. Run the deny path, see section 7.4.

Base URLs for the three protocols (<access-url> is the access URL filled in at install):

What you will see

• Step 1: that provider's Available switch in the provider list is on; the Available models column shows the enabled models. After save, "saved; model routing will sync shortly" is expected.
• Step 3: a successful playground shows a summary like "OK · first token … · total … · … tok · …". On failure the page states whether it happened on this platform or on the provider side, and a Chinese reason keyed by the error code.
• Step 6: expected result is HTTP/1.1 200, the body contains the model reply, and the response headers include x-request-id.
• Step 7: Gateway requests can find the same call; model, result, duration, and token usage match this call.
• When the business side needs another protocol, call once with each Base URL in the table; expected results are the same.

Note: model in the request must be a model name in the model group bound to that key (the name from the model plaza or from GET <OpenAI Base URL>/models). Otherwise it returns 404; see section 7.4.

Note: playground and real calls are both billed. The most recent calls show Pending billing on the usage page; that is a short billing delay.

Note: when the delivery scope includes MCP services or API services, add one "fetch a tool list + one side-effect-free tool call" and record it as its own row in section 7.6.

Note: an API key is shown only once. After copying, store it in the test machine's secret management. Do not paste it into a ticket, instant message, or screenshot.

7.4 Deny path and error-code check

Applies to: immediately after the successful call in section 7.3. That the gateway "rejects what it should reject, and states why" is as important as "the call works".

Procedure

1. Call once with a model name not in the availability scope: reuse the command in section 7.3, replacing <model-name> with a model name that is not in the model group bound to that key.
2. Call once with a disabled key: the tenant administrator finds the test key on the API key management tab under Admin Console → Organization & access → Model Groups, opens the detail, and clicks Disable (the test member can also Revoke a key created only for this test under Capability center → Home → API Keys), then calls again with that key.
3. (Optional) Call once after removing the test member from availability: Remove that member under Availability and quotas, then call again with a still-valid key.
4. Record each time: HTTP status, reason and code in the body, and response headers x-request-id and x-should-retry.
5. For rejects that can be tied to a member (steps 1 and 3), find the matching record in Gateway requests by x-request-id and confirm the result is failure and the reason matches the response.

# Host on the business network · ordinary user · read-only (status line and key error-body fields only)
curl -sS -i "<access-url>/api/v1/agent-gateway/openai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model-name-not-in-this-group>","messages":[{"role":"user","content":"hello"}],"max_tokens":8}'

The OpenAI-protocol error body looks like {"error":{"message","type","param","code","reason","request_id"}}, where reason is the stable error code (uppercase), code is the OpenAI-compatible code (lowercase), and request_id matches response header x-request-id. The Anthropic-protocol error body is {"type":"error","error":{"type","message","reason"},"request_id"}. The Gemini-protocol error body is {"error":{"code","message","status","details"}}, with code equal to the HTTP status.

What you will see (check against the product documentation site's Error reference page)

This acceptance must produce the first two rows: step 1 expects 404 LLM_MODEL_NOT_AVAILABLE; step 2 expects 401 (code invalid_api_key). The remaining rows are states that may appear during the POC, listed so on-site staff can judge them.

Note: under the same HTTP status, different reason values are handled completely differently. For example 403 may be an availability problem (ask an administrator to authorize) or a guardrail block (change the content); 429 may be a quota pool exhausted (retry will not help; adjust the quota) or upstream rate limiting (retry later); 503 may be a circuit open, upstream overload, or model routing not configured. Always judge by reason, not by status code, and do not parse message text (message changes across versions and is usually English).

Note: whether a retry is worth it is in response header x-should-retry: true means wait per Retry-After and retry; false means a retry will not change the result.

Note: 401 means the gateway did not recognize the caller. Those requests may not be searchable by initiator in Gateway requests. For 401, record the response itself (status, reason, x-request-id); whether the console can find it follows the actual result. Authenticated rejects such as 404 and 403 should be findable by request ID.

Note: a Disabled key cannot be re-enabled in the console. Do not disable the key delivered to the customer in section 7.3. Use a key created only for this test on the deny path.

7.5 Optional-capability acceptance

Applies to: this install enabled capabilities beyond core. Accept only capabilities that were purchased and enabled this time. Capabilities the product does not include, that were not purchased, or that are not enabled are recorded as Not applicable in section 7.6.

Prerequisite: first check capability state under System maintenance › System Updates. Present on this host, not enabled means not enabled. License does not include this capability means the license does not cover it. Record both as Not applicable; do not enable them temporarily for acceptance.

Procedure

Check the table item by item.

What you will see

• Enabled capabilities show as enabled in the System Updates capability list.
• When the two semantic-cache models are not set, a rule that turns semantic cache on cannot be saved. When a model is unavailable or the call fails, the second call still goes to upstream, and the request detail states the reason, for example "not involved: semantic-cache embedding model unavailable".
• When saving the semantic-cache rerank model, the system actually calls that model with built-in samples and sets the hit threshold. A model that cannot tell synonymous from non-synonymous questions cannot be saved; choose another rerank model.
• Knowledge base: when the license does not include knowledge base or the deployment did not install it, the Knowledge base tab in Capability center and the Knowledge bases menu in the admin console are both hidden.

Note: semantic cache applies only to OpenAI Chat Completions format, a single user message (a system or developer message may also be present), and a single-turn request whose body is at most 256 KiB. When calling through the OpenAI-compatible ingress (/api/v1/agent-gateway/openai/v1/*), a request is neither read from nor written to cache if the rule chain has multiple forward targets or failover, a per-request token cap, a mounted plugin, response rewrite, output detection or request-header rewrite, or if an Application quota sits before content detection, a prompt, or request rewrite. Other rules that carry a quota, and rules that forward to a single named upstream, do not affect the cache. When a cache miss happens during acceptance, first look at the Semantic cache line under Request destination on the call detail Routing and rewrite tab. Semantic cache is a dynamic-routing license module; record Not applicable when the license does not include it. Deployments that use OceanBase as the platform database do not support semantic cache; record Not applicable.

Note: changing the knowledge-base embedding model rebuilds vector indexes for every document; semantic retrieve is paused during rebuild. Decide the embedding model before acceptance.

Note: hosted agents and document parsing need a container runtime. Only hosted agents need to grant the service user container-runtime rights, which is equivalent to root on the host. Obtain written consent from the customer security owner before enabling hosted agents (section 3.4).

7.6 Acceptance record

Applies to: fill in as you go through acceptance. When finished, both the implementing party and the customer sign, and the table is filed with the handover materials.

Procedure

1. Fill in environment information first.
2. Run each row and fill in Result: Done, Not done (with reason and diagnostic code or reason), Not applicable.
3. For request rows, write x-request-id in Result.

Environment:

Acceptance items:

Signatures:

Note: any Not done row must state the reason, diagnostic code or reason, owner, and planned completion time; do not leave it blank. Rows that depend on a customer-external condition (upstream model egress, a license not yet issued) are Not done after stating the condition, not Not applicable.

Capability notes

Previous: 6. First sign-in and initialization · Next: 8. Required post-install work and day-to-day operations