How to View Container Logs with the Apple Container CLI

Use the container logs command to stream stdout/stderr from running containers, with options like --follow, --boot, and -n to control output.

The container CLI from the apple/container repository provides the primary interface to inspect output from containers running on macOS. Whether you need to debug application errors or monitor the boot sequence of the underlying virtual machine, the built-in logging commands give you direct access to the container's output streams without manually accessing log files. This guide covers how to view container logs using the native CLI tooling and explains the underlying architecture that streams log data from the service to your terminal.

How Container Log Streaming Works

The container logs command does not read static files from disk. Instead, it establishes a real-time connection to the Container API Service via XPC to stream log data directly from the container's file descriptor.

The XPC Communication Layer

When you execute container logs, the CLI (implemented in Sources/ContainerCommands/Container/ContainerLogs.swift) sends a request to the ContainerAPIService (Sources/Services/ContainerAPIService). The service opens a file descriptor pointing to the container's log stream and forwards that data back to the CLI through an XPC connection. The file descriptor key is defined in Sources/Services/ContainerAPIService/Client/XPC+.swift and referenced in ImageServiceXPCKeys.swift.

This architecture ensures that you see live output immediately, including both historical buffered lines and new entries as they are generated.

Log Types and Sources

The CLI distinguishes between two distinct log sources:

• Standard I/O (default): The combined stdout and stderr produced by the OCI-wrapped application running inside the container.
• Boot Log (--boot): Messages emitted by the container's init image and the virtual machine boot sequence, useful for debugging startup failures.

Command Syntax and Options

The basic syntax for viewing container logs follows this pattern:

container logs [OPTIONS] CONTAINER

The command supports several flags to filter and stream output:

• Default behavior: Displays all available standard output and error lines from the container's application.
• --boot: Switches the output source to show the VM boot log instead of application logs.
• -f or --follow: Streams new log entries continuously, similar to tail -f, until you interrupt with Ctrl-C.
• -n <N>: Limits output to the last N lines; if omitted, all available lines are printed.

Practical Examples

The following examples demonstrate common patterns for viewing container logs in different scenarios:

1. View the standard output of a running container

container logs my-web-server

2. Follow the log stream in real time

container logs --follow my-web-server

3. Show only the last 20 lines

container logs -n 20 my-web-server

4. View the boot process log instead of application output

container logs --boot my-web-server

5. Combine options to follow the boot log with line limiting

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

Viewing Machine Logs

For containers running inside a container machine, the CLI provides an analogous command implemented in Sources/ContainerCommands/Machine/MachineLogs.swift. The syntax and options remain identical:

container machine logs [OPTIONS] MACHINE_NAME

This command accesses the machine-level logs through the same XPC service architecture, allowing you to debug the hypervisor and VM management layer separately from individual container applications.

Log Storage and Error Handling

By default, the container CLI does not write logs to the macOS unified logging system. Logs exist only as streams accessible while the container runs. However, if you start the container system with the --log-root flag, log files are written to the specified directory for persistence.

When the service cannot access a container's log stream, it returns an error from Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift (specifically around line 760), which the CLI converts to a user-visible message such as "failed to open container logs." This typically occurs if the container has been removed or if the service connection is interrupted.

Summary

• Use container logs to access stdout/stderr from running containers via the XPC-based Container API Service.
• Reference key files: ContainerLogs.swift for the CLI implementation, ContainersService.swift for the server-side log FD handling, and XPC+.swift for the underlying communication protocol.
• Stream live output with --follow or inspect boot sequences with --boot.
• Limit output using -n to view only recent entries rather than the entire log history.
• Persist logs by starting the container system with --log-root if you need files written to disk.

Frequently Asked Questions

What is the difference between standard logs and boot logs?

Standard logs show the combined stdout and stderr from your application running inside the container, while boot logs (accessed with --boot) display the initialization sequence of the container VM, including messages from the init process and virtual machine startup. Use boot logs when debugging container startup failures before your application begins execution.

How do I save container logs to a file?

The CLI streams logs to stdout by default. To save logs to a file, redirect the output using standard shell redirection: container logs my-container > container.log. For persistent log files written by the system itself, start the container infrastructure with container system start --log-root /path/to/logs, which stores log files in the specified directory.

Why do I see "failed to open container logs"?

This error originates from ContainersService.swift (line 760) when the service cannot open the file descriptor for the container's log stream. This typically happens if the container has been deleted, if the Container API Service is not running, or if the container exited and its log buffers were cleared. Ensure the container is running and the service is active with container system status.

Can I view logs for containers that have already stopped?

The ability to view logs for stopped containers depends on whether the container system was started with the --log-root option. Without this flag, logs exist only as ephemeral streams and are lost when the container stops. With --log-root, log files are preserved on disk and can be inspected using standard Unix tools like cat or tail from the specified log directory.

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