# Runtime health and deployment results

Source: https://docs.imprezahost.com/runtime-health.html

See what the application is doing now, separately from what happened during its last deployment.

## Read the two results

The portal app card shows **Runtime**, the observation time and **Last operation**. REST deployment lists/details and MCP `impreza_list_deployments` return `runtime` and `last_operation`. A failed build can leave the previous application healthy. A successful deployment can later stop or become unhealthy.

The existing `status` field and status filter describe the deployment lifecycle. `last_health_at` is historical. Neither is proof that an application is currently available. Use `runtime.state` for the recent container observation; use `last_operation.status` and release history for the attempt.

## Runtime states

| State | Meaning at the observation time |
| --- | --- |
| `healthy` | All observed running containers report healthy Docker healthchecks, with no missing or stopped declared services and no detected failures. |
| `running` | Containers are running, but at least one has no confirmed healthcheck. Running does not mean verified healthy. |
| `starting` | A running container's healthcheck is still starting. |
| `degraded` | Unhealthy, failed, paused or restarting containers, or a stack with a missing/stopped declared service while other containers run. This includes completed one-shot services in a mixed stack. |
| `stopped` | No containers are running and no container failure was detected, or the managed application has no containers. |
| `unknown` | No usable recent observation. Read the reason before drawing a conclusion. |

## Freshness and disconnected agents

Agent 0.6.4 and later collect container state during their heartbeat, normally every 30 seconds. Observations expire after 120 seconds. If the agent has not communicated for more than 90 seconds, current runtime becomes unknown with `agent_offline`; the containers may still be running. Poll traffic alone cannot refresh an old runtime observation.

Other reasons are `not_reported` (no report, including older agents), `not_observed` (this app was absent from the snapshot), `collection_failed` and `stale`. `observed_at`, `age_seconds` and `last_reported_state` retain the context of the last reading. Old counters are historical when state is unknown. The portal keeps the runtime badge and observation timestamp received when the page loads. Leaving the page open or returning to the tab does not change that snapshot. Click **Refresh** or reload to request a new reading; the server then applies the freshness limits above. Automatic deployment-progress updates preserve the runtime snapshot for existing cards. A displayed healthy snapshot does not guarantee that the app is still healthy now.

Existing customers can follow [Update your agent](/agent-updates.html). Updates remain a customer action and preserve agent identity, configuration and applications. No fleet update is automatic. Keep the VPS clock synchronized; old or excessively future-dated reports are rejected.

## REST and MCP

Read `GET /v1/platform/deployments`, `GET /v1/platform/deployments/{id}`, or the equivalent custom deployment endpoints. MCP 0.23.0 documents these fields in `impreza_list_deployments`; generic reads can use `impreza_api_search` and `impreza_api_call`.

```
{
  "status": "failed",
  "last_operation": {"kind": "deploy", "status": "failed"},
  "runtime": {
    "state": "healthy",
    "reason": null,
    "observed_at": "2026-09-14T16:00:00Z",
    "age_seconds": 8,
    "fresh_for_seconds": 120,
    "scope": "containers"
  }
}
```

This example means the last deployment failed while the latest observed containers were healthy. It does not identify which source revision is serving traffic; consult [release history and recovery](/deployment-safety.html).

## Application diagnostics and next steps

**Release status:** available in the portal and deployment detail API. Existing MCP clients can read it with `impreza_api_call`; no agent or client package update is required.

Open **Diagnostics and history** on an app card, or read `GET /v1/platform/deployments/{id}` with read scope. The same endpoint covers catalog and custom apps. MCP users can call `impreza_api_call` with the following arguments; no new tool or agent version is required to interpret existing observations.

```
{"path":"/platform/deployments/dpl_your_app"}
```

The additive `diagnostics` object uses schema `deployment-diagnostics-v1`. It contains `generated_at`, `runtime_state`, `runtime_observed_at`, ordered `findings` (code, severity, summary, next\_action, basis), and `not_checked`. It is a summary of recorded observations: `is_live_check=false` and `automatic_actions=false`. List endpoints and the custom-specific detail endpoint keep their existing shape; use the common detail URL above for diagnostics.

Recovery requiring support, reconciliation in progress and result delivery take priority over a healthy container observation. Wait for the recorded outcome before retrying. A failed operation can coexist with healthy containers; neither identifies which release is serving. Failure causes are correlated only when the history entry matches the exact latest operation. An older Git/build error is not attributed to a newer restart.

Unknown, stale or offline readings are never promoted to healthy. The report keeps container observations separate from operation results and returns fixed descriptions rather than raw errors, logs, URLs or credentials. It does not probe public HTTP, DNS, TLS or external dependencies. Check those separately. The report is a snapshot; close and reopen it to refresh. Cross-account or orphaned deployments return 404. The portal also requires permission to view services and a valid session token; refresh the page if access is refused.

## Check public HTTPS

The portal and hosted MCP provide this check. The local MCP tool requires MCP 0.36.0 or later; no agent update is needed.

Choose **Check public HTTPS** in Diagnostics and history, call `POST /v1/platform/deployments/{id}/probe` with read scope, or use the MCP tool `impreza_probe_deployment` with `{"deployment_id":"dpl_your_app"}`. Only the deployment's saved hostname is used; no URL or credentials can be supplied. The generic GET-only MCP reader cannot invoke this POST.

The `deployment-network-probe-v1` response separates public DNS resolution, TLS verification and the HTTP HEAD status. A 2xx response verifies only the root endpoint's HEAD response. Redirects are reported without contacting their destination. 405 can mean the app does not support HEAD; it does not prove a general outage. No body, cookies, credentials or response headers are returned. Dependencies, database correctness and certificate expiry are not checked.

Every DNS answer must be public. The connection is pinned to one validated address, system proxies are disabled and certificate/hostname verification stays enabled. The HTTPS connection has an eight-second timeout; system DNS resolution uses the host resolver's own timeout. This is one observation from the API server, not every address, region or user network. A 30-second account-wide cooldown is shared across portal, REST and MCP; concurrent attempts return 429. Missing limiter storage returns 503 without a network request. No automatic repair is performed.

## Scope and limits

This is a Docker container observation, not an external HTTP, DNS, TLS, database consistency or business-function test. No automatic repair or traffic switch is performed. Declared Compose services are checked for presence; desired replica counts and external dependencies are not verified. Container names, environment variables and healthcheck logs are not sent with this report.

Collection has an eight-second total budget, a two-second budget per app, a maximum of 100 state-directory entries and 100 containers per app. Failures or partial collections leave affected apps unknown rather than inferring stopped or healthy. Very large or busy servers can therefore have incomplete observations.

For deploy-time enforcement, see [Required healthy startup](/tutorials/agent-apps-panels.html#required-startup). For runtime investigation, use application logs and the server diagnostics.

To stop queued work or preparation before container replacement, see [Cancel a deployment](/deployment-cancellation.html).

Read [Deployment progress and interrupted agents](/deployment-progress.html) for step reports, persistent result delivery and operations that require reconciliation.