# How to Access and Debug Container Logs in Apple Container > Effectively access and debug container logs using the apple/container CLI. Learn to retrieve application and VM boot logs seamlessly. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-10 --- **The `container` CLI provides a unified way to retrieve both application stdout/stderr and virtual-machine boot logs for any running container by forwarding requests to the Containerization service.** The **apple/container** project implements a lightweight OCI runtime that uses the macOS Virtualization framework to host containers inside lightweight VMs. Understanding how to access and debug container logs requires familiarity with the two distinct log streams—standard I/O from the container's pseudo-TTY and kernel-level boot logs from the VM itself—and the specific CLI commands that expose them. ## Understanding the Logging Architecture The logging system in `apple/container` separates application output from virtualization layer diagnostics. According to [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md), the `container` binary communicates with the Containerization service, which interacts with the macOS Virtualization framework to fetch logs from the underlying VM. ### Standard I/O Logs from the PTY During normal operation, the container's stdout and stderr are collected from the pseudo-TTY (PTY) stream attached to the container process. As documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 84-94), these logs represent your application's standard output and are retrieved using the `container logs` command without any special flags. ### Boot Logs from the VM Kernel Ring Buffer When debugging startup failures or init-script issues, you can access the VM's `dmesg` or kernel message buffer. The `--boot` flag instructs the Containerization service to read from the VM's kernel ring buffer rather than the container's PTY stream, as specified in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md). ### System-Level Service Logs Beyond individual container logs, the `container system logs` command exposes logs generated by the container infrastructure itself—including the registry, DNS, and other internal services. This is covered in the "View system logs" section of [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md). ## Retrieving Application Logs To view the standard output of a running container, use the `container logs` command followed by the container name or ID. ```bash # Display all available logs for a container container logs my-web-server ``` For real-time monitoring, append the `--follow` (or `-f`) flag to tail the log stream as new lines are written: ```bash # Follow logs in real-time (similar to tail -f) container logs -f my-web-server ``` To limit output to the most recent entries, use the `-n` flag with a line count: ```bash # Retrieve only the last 20 lines container logs -n 20 my-web-server ``` You can also redirect logs to a file for offline analysis: ```bash # Pipe logs to a file for later inspection container logs my-web-server > my-web-server.log ``` ## Debugging Boot Sequences When a container fails to start or you need to debug initialization scripts running before the main application, access the VM boot logs using the `--boot` flag. ```bash # View the VM boot sequence container logs --boot my-web-server ``` Combine `--boot` with `--follow` to monitor the boot process in real-time as the VM initializes: ```bash # Follow the boot log as the VM boots container logs --boot -f my-web-server ``` This accesses the VM's `dmesg` buffer through the Containerization service, revealing kernel messages and early-boot diagnostics that occur before the container's PTY becomes available. ## Configuring Log Storage By default, logs flow through the macOS Unified Logging facility. However, you can configure persistent file-based logging by setting the `--log-root` directory when starting the container system. As documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) under the `container system start` entry and detailed in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), the `--log-root` flag writes logs to files under the specified directory instead of routing through the macOS log facility: ```bash # Start the container system with persistent log storage container system start --log-root /var/log/containers ``` ## Collecting Logs for Bug Reports When reporting issues to the apple/container maintainers, gather comprehensive logs using the commands referenced in [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md). Collect both application logs and system logs: ```bash # Get system-level logs (registry, DNS, etc.) container system logs | tail -8 # Get specific container logs container logs --boot my-container > boot.log container logs my-container > app.log ``` ## Summary - **Standard application logs** are retrieved via `container logs ` from the container's PTY stream. - **Boot diagnostics** require the `--boot` flag to access the VM's kernel ring buffer (`dmesg`). - **Real-time monitoring** uses `--follow` (`-f`), while **line limiting** uses `-n `. - **System infrastructure logs** are available through `container system logs`. - **Persistent storage** is configured via `--log-root` in `container system start`. - Source documentation resides in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md), [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), and [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md). ## Frequently Asked Questions ### What is the difference between `container logs` and `container system logs`? `container logs` retrieves output from a specific container's pseudo-TTY or VM boot buffer, showing application stdout/stderr or kernel messages. `container system logs` displays logs generated by the container infrastructure itself—including the registry service, DNS resolution, and other internal components—accessible according to [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md). ### How do I view logs from a container that crashed during startup? Use the `--boot` flag with `container logs` to access the VM's kernel message buffer. Since standard I/O logs require the container process to be running with an attached PTY, boot logs provide visibility into initialization failures, kernel panics, or script errors that occur before the container runtime fully starts. ### Can I follow logs in real-time without outputting the entire history? Yes. Combine the `--follow` (`-f`) flag with the `-n` option to start following from a specific line count. For example, `container logs -f -n 10 my-container` begins showing only the last 10 lines and then continues to stream new entries as they occur, according to the `container logs` specification in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md). ### Where are logs stored when I use `--log-root`? When you start the container system with `container system start --log-root `, the Containerization service writes log files to the specified directory path instead of routing through the macOS Unified Logging system. The exact file structure and rotation policies are detailed in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).