# Implementing Container Health Checks and Monitoring Status in apple/container > Learn to implement container health checks and monitor status in apple/container using its XPC-based health-check mechanism. Get runtime info for your API server and container system today. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-04 --- **The apple/container project uses a lightweight XPC-based health-check mechanism to expose runtime information about the API server and the overall container system.** The `apple/container` repository provides a robust subsystem for implementing container health checks using Cross-Process Communication (XPC). This architecture enables both internal components and external monitoring tools to verify daemon liveness and retrieve version metadata through a simple ping-reply protocol. By leveraging the **HealthCheckHarness** and **ClientHealthCheck** classes, developers can integrate health monitoring into Swift applications or command-line workflows. ## Health Check Architecture Overview The health check system operates on a client-server model using XPC messages. The server exposes a `ping` route that returns a **SystemHealth** payload containing file system paths and version metadata. Clients connect via `XPCClient(service: "com.apple.container.apiserver")` to request this snapshot. This design supports both ad-hoc diagnostics and continuous monitoring without heavy resource overhead. ## Server-Side Implementation The API server registers health check routes during startup and handles incoming requests through a dedicated harness class. ### Registering the Ping Route During initialization in `Sources/APIServer/APIServer+Start.swift`, the server registers the `XPCRoute.ping` route. The registration occurs within the `initializeHealthCheckService` method, typically invoked between lines 48-62. This route maps incoming XPC messages to the `HealthCheckHarness` handler. ### The HealthCheckHarness Class Located in [`Sources/Services/ContainerAPIService/Server/HealthCheck/HealthCheckHarness.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/HealthCheck/HealthCheckHarness.swift), this class implements the `ping(_:)` method that constructs the health response. The method builds an `XPCMessage` reply containing: - **appRoot**: Absolute URL of the application data directory - **installRoot**: Absolute URL of the installation directory - **logRoot**: Optional location of log files - **apiServerVersion**, **apiServerCommit**, **apiServerBuild**, **apiServerAppName**: Version-control metadata from the build system ```swift // HealthCheckHarness.swift (excerpt) @Sendable public func ping(_ message: XPCMessage) async -> XPCMessage { let reply = message.reply() reply.set(key: .appRoot, value: appRoot.absoluteString) reply.set(key: .installRoot, value: installRoot.absoluteString) if let logRoot { reply.set(key: .logRoot, value: logRoot.string) } reply.set(key: .apiServerVersion, value: ReleaseVersion.singleLine(appName: "container‑apiserver")) reply.set(key: .apiServerCommit, value: get_git_commit().map { String(cString: $0) } ?? "unspecified") reply.set(key: .apiServerBuild, value: ReleaseVersion.buildType()) reply.set(key: .apiServerAppName, value: "container‑apiserver") return reply } ``` ## Client-Side Implementation Client code initiates health checks and decodes responses into strongly-typed Swift structures. ### Sending Requests with ClientHealthCheck The `ClientHealthCheck` class in [`Sources/Services/ContainerAPIService/Client/ClientHealthCheck.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/ClientHealthCheck.swift) provides the primary interface for client-side health monitoring. The static method `ping(timeout:)` creates an XPC client, sends a `XPCMessage(route: .ping)`, and awaits the reply. ```swift // ClientHealthCheck.swift (excerpt) public static func ping(timeout: Duration? = XPCClient.xpcRegistrationTimeout) async throws -> SystemHealth { let client = Self.newClient() let request = XPCMessage(route: .ping) let reply = try await client.send(request, responseTimeout: timeout) guard let appRootValue = reply.string(key: .appRoot), let appRoot = URL(string: appRootValue) else { throw ContainerizationError(.internalError, message: "failed to decode appRoot in health check") } // …decode other fields… return .init(appRoot: appRoot, installRoot: installRoot, logRoot: logRoot, apiServerVersion: apiServerVersion, apiServerCommit: apiServerCommit, apiServerBuild: apiServerBuild, apiServerAppName: apiServerAppName) } ``` ### The SystemHealth Data Model The response decodes into a **SystemHealth** struct defined in [`Sources/Services/ContainerAPIService/Client/SystemHealth.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/SystemHealth.swift). This immutable value type exposes properties for all server-reported metadata, enabling type-safe access to health information throughout the client codebase. ## CLI Commands and Monitoring The container CLI exposes health data through user-friendly commands suitable for both interactive use and automation. ### System Status Command The `container system status` command, implemented in [`Sources/ContainerCommands/System/SystemStatus.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/System/SystemStatus.swift), invokes `ClientHealthCheck.ping` with a default timeout of 10 seconds. It renders output in either table or JSON format based on the `--format` flag. ```swift // SystemStatus.run() (excerpt) let systemHealth = try await ClientHealthCheck.ping(timeout: .seconds(10)) let status = PrintableStatus( status: "running", appRoot: systemHealth.appRoot.path(percentEncoded: false), installRoot: systemHealth.installRoot.path(percentEncoded: false), logRoot: systemHealth.logRoot?.string, apiServerVersion: systemHealth.apiServerVersion, apiServerCommit: systemHealth.apiServerCommit, apiServerBuild: systemHealth.apiServerBuild, apiServerAppName: systemHealth.apiServerAppName ) ``` ```bash # Show a concise status table container system status --format table # Get JSON output for downstream processing container system status --format json ``` ### Continuous Monitoring Patterns For production monitoring, implement a polling loop that repeatedly calls `ClientHealthCheck.ping`. This pattern detects daemon crashes, version drift, or connectivity issues. ```swift import ContainerAPIClient import Logging let logger = Logger(label: "health.monitor") Task { while true { do { let health = try await ClientHealthCheck.ping() logger.info("apiserver alive – version \(health.apiServerVersion)") } catch { logger.error("apiserver unreachable: \(error)") } try await Task.sleep(nanoseconds: 10_000_000_000) // 10 s } } ``` ## Practical Implementation Examples Integrate health checks into custom Swift tooling using the ContainerAPIClient package. ### Basic Health Check Script ```swift import ContainerAPIClient // pulls in ClientHealthCheck & SystemHealth import Foundation @main struct HealthCheckDemo { static func main() async { do { let health = try await ClientHealthCheck.ping(timeout: .seconds(5)) print("API server up – version: \(health.apiServerVersion)") print("App root: \(health.appRoot.path)") print("Install: \(health.installRoot.path)") if let log = health.logRoot { print("Log root: \(log.string)") } } catch { print("Health check failed: \(error)") } } } ``` ## Summary - **XPC-Based Architecture**: The apple/container project implements container health checks using a lightweight XPC ping-reply mechanism between client and server components. - **Server Components**: The `HealthCheckHarness` in [`Sources/Services/ContainerAPIService/Server/HealthCheck/HealthCheckHarness.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/HealthCheck/HealthCheckHarness.swift) assembles runtime metadata including paths and version info. - **Client API**: `ClientHealthCheck.ping(timeout:)` provides an async/await interface for retrieving `SystemHealth` structs from [`Sources/Services/ContainerAPIService/Client/SystemHealth.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/SystemHealth.swift). - **CLI Integration**: The `container system status` command offers human-readable and JSON output formats for operational monitoring. - **Monitoring Strategy**: Implement polling loops using `ClientHealthCheck` with appropriate timeouts to continuously verify daemon liveness. ## Frequently Asked Questions ### How does the apple/container health check mechanism work? The mechanism uses XPC (Cross-Process Communication) to send ping messages from a client to the container API server. The server responds with a `SystemHealth` payload containing file system paths and build metadata, enabling clients to verify both connectivity and correct installation. ### What information does the SystemHealth struct contain? According to the source code in [`Sources/Services/ContainerAPIService/Client/SystemHealth.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/SystemHealth.swift), the struct contains `appRoot`, `installRoot`, and optional `logRoot` URLs, plus version metadata including `apiServerVersion`, `apiServerCommit`, `apiServerBuild`, and `apiServerAppName`. ### How can I monitor container health checks programmatically? Import the `ContainerAPIClient` module and call `ClientHealthCheck.ping(timeout:)` from your Swift code. You can embed this in a `Task` with `Task.sleep` for continuous polling, or invoke the `container system status --format json` command from shell scripts for integration with monitoring systems. ### What timeout should I use for ClientHealthCheck.ping? The default timeout uses `XPCClient.xpcRegistrationTimeout`, but you should specify an explicit duration based on your network environment. The CLI commands typically use `.seconds(10)`, while interactive scripts may prefer shorter timeouts like `.seconds(5)` for faster feedback.