How to Access Application and VM Boot Logs for Debugging Container Issues

Use container logs <id> to stream application STDIO and container logs --boot <id> to retrieve VM bootstrap logs when debugging issues in the apple/container ecosystem.

Effective debugging of containerized workloads requires visibility into both the application layer and the underlying virtualization stack. The apple/container repository provides native CLI commands to access standard output streams from OCI containers and low-level boot logs from the hosting VM. This guide demonstrates how to access application and VM boot logs for debugging container issues using the official Container CLI.

Retrieving Application Logs (STDIO)

The primary interface for accessing container output is the container logs command, which streams the STDIO files of the container's main process.

Viewing Complete Log History

To retrieve the full application log file for a specific container, execute the logs command with the container identifier:

container logs my-web-server

Limiting Output to Recent Entries

When investigating recent failures, use the -n flag to restrict output to the last N lines. This behaves similarly to the standard tail -n utility:

container logs -n 100 my-web-server

Real-Time Log Streaming

For active debugging sessions, the --follow (-f) flag enables real-time streaming of new log entries as they are written:

container logs --follow my-web-server

Accessing VM Boot Logs

Application logs capture container output, but initialization failures often manifest in the VM bootstrap process. The container runtime uses a minimal init daemon (vminitd) that writes its own log file.

To retrieve these low-level boot logs, use the --boot flag:

container logs --boot my-web-server

According to the source code in Sources/ContainerResource/Container/Bundle.swift (lines 37-40), the --boot flag directs the CLI to open the bundle's boot-log file defined by Bundle.bootlog, which resolves to vminitd.log within the container's bundle directory. This file contains the initialization sequence of the micro-VM hosting the container.

Debugging Container Machine Logs

For workflows utilizing the higher-level "machine" abstraction, the same logging interface applies through the container machine logs command.

Machine Application Logs

To access STDIO logs from a container machine:

container machine logs dev-machine

Machine Boot Logs

To retrieve the VM boot log for a container machine, combine the machine command with the --boot flag:

container machine logs --boot dev-machine

As implemented in Sources/ContainerCommands/Machine/MachineLogs.swift (lines 29-60), the machine logs command supports the same output-limiting and follow flags as the standard container logs interface.

Implementation Details

The CLI routes log requests to dedicated service layers that handle file system interactions. In Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift (lines 726-760), the service reads log files directly from the container bundle and returns file handles to the CLI for streaming. This architecture ensures efficient access to both application STDIO streams and the vminitd boot logs without requiring direct filesystem access to the host.

Summary

• Use container logs <id> to access application STDIO output from the container's main process
• Append -n <number> to limit output to recent lines, or --follow to stream new entries in real-time
• Use container logs --boot <id> to retrieve the VM boot log (vminitd.log) from the container bundle
• For container machines, use container machine logs with the same flags, including --boot for VM initialization logs
• Log files are read from the bundle directory via the Container API service, ensuring consistent access patterns

Frequently Asked Questions

What is the difference between application logs and VM boot logs?

Application logs contain the STDIO streams (stdout and stderr) produced by the container's main OCI process. VM boot logs, accessed via the --boot flag, contain the initialization sequence of the vminitd daemon that runs inside the micro-VM before the container starts. These boot logs are essential for debugging VM-level failures that occur before the application executes.

Where are the VM boot logs stored on the filesystem?

The VM boot logs are stored as vminitd.log within the container's bundle directory. According to the Bundle implementation in Sources/ContainerResource/Container/Bundle.swift, the Bundle.bootlog property references this file at …/vminitd.log inside the bundle structure.

Can I follow boot logs in real-time like application logs?

Yes. Combine the --boot and --follow flags to stream the VM boot log as it is being written. This is particularly useful when initializing new containers or diagnosing slow boot sequences:

container logs --boot --follow my-web-server

Do these commands work with container machines as well?

Yes. The container machine logs command supports both application and boot log access. Omit the --boot flag to view the container's STDIO logs, or include it to view the VM boot log for the machine instance, as defined in Sources/ContainerCommands/Machine/MachineLogs.swift.

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