How to Inspect Container and Image Details Using the container inspect Command

The container inspect and container image inspect commands retrieve low‑level, machine‑readable JSON details about containers and images by querying the container‑apiserver backend via a local Unix-domain socket or HTTP+TLS connection.

The apple/container repository provides a CLI for managing OCI containers and virtual machines on macOS. When you need to examine the internal state of a running container or the metadata of a stored image, the container inspect command serves as the primary interface for accessing this structured data. It returns comprehensive JSON output describing resource limits, mounts, network interfaces, image manifests, and platform-specific variants.

How the container inspect Command Works

The container inspect family of commands operates by building an InspectRequest model and forwarding it to the container‑apiserver, the backend service that manages VMs, OCI images, and virtual networking. According to Sources/ContainerCLI/Commands/InspectCommand.swift, the CLI parses arguments and constructs this request object before transmission.

The request travels over a local Unix-domain socket (or HTTP+TLS on macOS) to the server-side handler defined in Sources/ContainerServer/Handlers/InspectHandler.swift. This handler retrieves the current state from the internal ContainerRuntime and ImageStore components, then serializes the response using the data models defined in Sources/ContainerCore/Models/InspectOutput.swift.

Inspecting Running Containers

To inspect a running container, use container inspect <container-ids>. This command asks the apiserver for the current state of each specified container, including resource limits, mounts, network interfaces, PID, and exit code. The CLI prints raw JSON to stdout, which you typically pipe to jq for readability.

The official documentation in docs/command-reference.md (lines 431‑449) provides the exact syntax for this operation.

Inspecting OCI Images

For image inspection, use container image inspect <images>. This performs the same underlying operation on one or more OCI images, returning JSON containing the image manifest, config, layer digests, and platform-specific variant information.

Refer to docs/command-reference.md (lines 682‑694) for the detailed command syntax.

Implementation Details

The inspection flow relies on several key components working together:

• Sources/ContainerCLI/Commands/InspectCommand.swift: Parses container inspect arguments and builds the InspectRequest model.
• Sources/ContainerCore/Networking/ContainerAPIServerClient.swift: Sends the request to the apiserver and returns the JSON payload.
• Sources/ContainerServer/Handlers/InspectHandler.swift: Retrieves container and image state from the runtime and encodes it as JSON.
• Sources/ContainerCore/Models/InspectOutput.swift: Defines Swift structs that mirror the JSON schema for containers, images, networks, and volumes.

Practical Examples

Here are runnable examples for common inspection tasks:

# Show detailed JSON for a running container named "my-web-server"

container inspect my-web-server | jq .

# Inspect multiple containers at once and extract specific fields

container inspect web db cache | jq '.[] | {id, status, resources}'

# Pretty-print an image's manifest and config

container image inspect alpine:3.22 | jq .

# Use --debug to see the raw HTTP request/response for troubleshooting

container inspect --debug my-web-server

Summary

• The container inspect command provides low-level JSON data about containers, images, networks, and volumes by querying the container‑apiserver.
• Implementation files include Sources/ContainerCLI/Commands/InspectCommand.swift for CLI parsing and Sources/ContainerServer/Handlers/InspectHandler.swift for server-side data retrieval.
• Output format is pure JSON, enabling programmatic use with tools like jq, yq, or gojq.
• Debug mode (--debug) exposes raw HTTP request/response diagnostics when the server is unreachable.

Frequently Asked Questions

What is the difference between container inspect and container image inspect?

container inspect retrieves runtime state information about running or stopped containers, including resource limits, mounts, and network interfaces. container image inspect queries metadata about OCI images stored in the local ImageStore, returning manifest details, layer digests, and configuration data. Both commands use the same underlying InspectRequest mechanism but target different resource types.

How can I filter the JSON output to show only specific fields?

Because the output is pure JSON, you can pipe the command to jq or similar tools. For example, container inspect web | jq '.[] | {id, status, resources}' extracts only the ID, status, and resources fields from the inspection results. This approach works for both container and image inspections.

Where does the inspection data originate in the apple/container architecture?

The data comes from the ContainerRuntime and ImageStore components within the container‑apiserver. When you run an inspect command, the ContainerAPIServerClient in Sources/ContainerCore/Networking/ContainerAPIServerClient.swift sends the request to the server, where InspectHandler.swift gathers the current state and serializes it using the models defined in Sources/ContainerCore/Models/InspectOutput.swift.

How do I troubleshoot when container inspect returns an error or fails to connect?

Use the --debug flag to expose raw HTTP request and response diagnostics. This shows the exact communication between the CLI and the container‑apiserver, helping identify network issues, authentication problems, or server unavailability. The debug output is particularly useful when the apiserver is unreachable via the Unix-domain socket or HTTP+TLS connection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}