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

> Learn to access container logs and debug startup issues in Apple Container using `container logs` and other commands. Diagnose application, VM boot, or runtime failures effectively.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-11

---

**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:
   
   ```bash
   container logs my-web-server
   ```

2. **Inspect the VM boot log** if the container output is empty or incomplete:
   
   ```bash
   container logs --boot my-web-server
   ```

3. **Follow logs in real-time** when failures occur after timeouts:
   
   ```bash
   container logs --boot -f my-web-server
   ```

4. **Limit to recent lines** when dealing with large log files:
   
   ```bash
   container logs -n 50 my-web-server
   ```

5. **Review system logs** for runtime-level errors:
   
   ```bash
   container system logs --last 10m
   ```

6. **Check machine logs** for VM-wide issues like network failures:
   
   ```bash
   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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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

```bash

# 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`](https://github.com/apple/container/blob/main/RuntimeService.swift), [`StandardError.swift`](https://github.com/apple/container/blob/main/StandardError.swift), and [`ProgressBar.swift`](https://github.com/apple/container/blob/main/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`.