How to Access Container Logs and Debug Startup Issues in Apple Container

Use container logs, container logs --boot, and container system logs to diagnose failures at the application, VM boot, or runtime level.

The Apple Container project provides a Swift-based runtime for Linux containers on macOS, with built-in CLI tools to access container logs and debug startup issues. Whether a container fails to launch its main process or the underlying VM experiences boot failures, the container command-line tool offers structured logging commands to pinpoint the root cause.

Core Logging Commands

Stream Container Stdio with container logs

The container logs <container-id> command streams the standard output and error of the container’s main process. According to the command reference in docs/command-reference.md#L411-L429, this is the first diagnostic tool to check when an application fails unexpectedly.

Common flags include -f (or --follow) to tail logs continuously, and -n <N> to limit output to the last N lines.

Inspect VM Boot Logs with --boot

When a container never reaches its main process, the failure often occurs during VM initialization. The container logs --boot <container-id> command displays the VM boot log instead of container stdio, showing kernel messages, init-system output, and custom init logic as documented in docs/how-to.md#L629-L632.

This is critical for diagnosing early-stage failures like kernel panics or init script errors.

Monitor System-Level Events

The container system logs command displays messages emitted by the container service itself, including resource allocation errors and health-check failures documented in docs/command-reference.md#L1443-L1459. Use --last <time> (e.g., 5m, 1h) to view recent activity.

Debug Container Machine Logs

For issues affecting the entire VM rather than individual containers, use container machine logs <machine-id>. This retrieves logs from the container machine (the VM that hosts multiple containers), with the --boot flag available to examine startup sequences.

Debugging Startup Failures: A Systematic Workflow

When a container fails to start, follow this sequence to isolate the failure layer:

1. Check the container’s stdio to see if the main process produced any output:

   container logs my-web-server

2. Inspect the VM boot log if the container output is empty or incomplete:

   container logs --boot my-web-server

3. Follow logs in real-time when failures occur after timeouts:

   container logs --boot -f my-web-server

4. Limit to recent lines when dealing with large log files:

   container logs -n 50 my-web-server

5. Review system logs for runtime-level errors:

   container system logs --last 10m

6. Check machine logs for VM-wide issues like network failures:

   container machine logs --boot my-machine

Source Code Implementation

The logging infrastructure in the Apple Container repository integrates with Swift’s swift-log API to ensure structured, searchable output across all components.

RuntimeService.swift

In Sources/Services/RuntimeLinux/Server/RuntimeService.swift#L273-L300, the RuntimeService class sets up the logger for the Linux container runtime and manages the boot log file (BootLog.file). This is where the infrastructure writes VM boot messages that you access via the --boot flag.

StandardError.swift

The Sources/TerminalProgress/StandardError.swift file provides a thin wrapper that forwards container stderr streams to the macOS unified logging system, ensuring that error output from the container process is captured alongside system logs.

ProgressBar.swift

Located in Sources/TerminalProgress/ProgressBar.swift, this component handles CLI progress indicators using the same swift-log logger that powers the log commands, ensuring consistent log formatting across the user interface and backend services.

Practical Code Examples

# Show the last 100 lines of a container's stdout

container logs -n 100 my-app

# Follow the boot log while the VM starts

container logs --boot -f my-app

# Filter boot log entries containing custom init markers

container logs --boot my-app | grep custom-init

# View recent system-level messages (last 5 minutes)

container system logs --last 5m

# Debug a container-machine by watching its boot log

container machine logs --boot -f my-machine

Summary

• Use container logs to inspect application stdio, with -f for real-time following and -n to limit line count.
• Use container logs --boot to diagnose VM initialization failures before the container process starts.
• Use container system logs to investigate runtime errors and resource issues at the service level.
• Use container machine logs for VM-wide diagnostics affecting multiple containers.
• The logging infrastructure resides in RuntimeService.swift, StandardError.swift, and ProgressBar.swift, utilizing the swift-log API for structured output.

Frequently Asked Questions

What is the difference between container logs and container logs --boot?

The container logs command shows standard output and error from the container's main process, while container logs --boot displays the VM boot log containing kernel messages and init-system output. Use --boot when the container fails before reaching its main entry point, as implemented in Sources/Services/RuntimeLinux/Server/RuntimeService.swift#L273-L300.

How do I view logs in real-time as a container starts?

Add the -f or --follow flag to any logs command. For example, container logs -f my-app follows the container's stdio, and container logs --boot -f my-app follows the VM boot log. This is essential for catching timing-dependent startup failures.

Where does the Apple Container runtime store boot logs?

According to the source code in Sources/Services/RuntimeLinux/Server/RuntimeService.swift#L273-L300, the runtime writes boot logs to a file referenced by BootLog.file during VM initialization. The container logs --boot command reads this file, which contains kernel messages and custom init logic output.

When should I use container system logs instead of container-specific logs?

Use container system logs when the container service itself reports errors—such as missing resources, permission problems, or health-check failures—rather than application-level failures. This command queries the macOS unified logging subsystem where the container runtime writes system-level messages, as documented in docs/command-reference.md#L1443-L1459.

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