How to Access and Debug Container Logs in Apple Container

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, 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 (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.

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.

Retrieving Application Logs

To view the standard output of a running container, use the container logs command followed by the container name or ID.

# 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:

# 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:

# Retrieve only the last 20 lines

container logs -n 20 my-web-server

You can also redirect logs to a file for offline analysis:

# 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.

# 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:

# 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 under the container system start entry and detailed in 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:

# 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. Collect both application logs and system logs:

# 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 <name> 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 <number>.
• 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, docs/command-reference.md, and 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.

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.

Where are logs stored when I use --log-root?

When you start the container system with container system start --log-root <directory>, 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.

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