Logging

Corral captures logs from every running project and from infrastructure services (DNS and proxy) through a unified disk-backed pipeline. All log entries are persisted to ~/.corral/logs/ with automatic rotation and retention management. You can view, search, and stream logs from the CLI or the macOS app, with filtering by severity, source, stream, and lifecycle phase.

Viewing Logs

All projects:

corral logs

A specific project:

corral logs my-worker

Last N entries:

corral logs --tail 20

Log entries show a timestamp, project name, and message:

[2026-04-29 14:32:01] my-app           | Ready on http://localhost:8787
[2026-04-29 14:32:05] auth-service     | Ready on http://localhost:8788

Stderr entries are displayed in red in the terminal.

Real-Time Streaming

Follow logs as they arrive:

corral logs --follow

Or for a specific project:

corral logs my-worker --follow

In follow mode, Corral shows the most recent 50 entries and then streams new output in real time. Customize the initial history with --tail:

corral logs --follow --tail 10

Searching

Filter logs by text content (case-insensitive):

corral logs --search "error"

Combine with a project filter:

corral logs my-worker --search "database"

Log Persistence and Retention

Logs are persisted to disk in ~/.corral/logs/ via a disk-backed unified pipeline, with separate log files per unit (projects, services, infrastructure). Logs survive daemon restarts — when Corral starts, it reloads the persisted history.

Log files are automatically rotated when they exceed a configurable size (default 10 MB per unit). During rotation, older entries are evicted and the most recent entries are kept. You can configure the retention limit in Settings → Logging.

Failure snapshots are a special category: when a unit fails, Corral captures a snapshot of the most recent log entries (typically the last 100 lines) and stores it in ~/.corral/units/<id>/snapshots/<failure-id>.json. These snapshots are capped at 50 per unit (FIFO eviction) and are accessible via the Failure History tab in the macOS app or via the corral status --json output’s last_failure field.

In the macOS App

The macOS app provides a visual log viewer accessible from:

• Per-project: The Logs tab in each project’s detail view
• Global: The Logs panel in the sidebar

On Pro projects, browser console output captured by Browser & Network also folds into this unified view, so console messages sit inline with server output.

The log viewer features:

• Styled text display — timestamps in gray, origin labels in secondary color, messages in monospaced font
• Source filter — show all entries, or filter by origin: Corral, Process, Caddy, DNS
• Stream filter — show all, stdout only, or stderr only
• Severity filter — show all, or filter by minimum severity: Debug, Info, Warn, Error
• Lifecycle pills — inline pills next to log entries that mark lifecycle transitions (Starting, Ready, Stopping, Failed)
• Health signal indicators — inline indicators for health state changes (Degraded, Critical, recovered to Nominal)
• Text filter — narrow down entries by content
• Cmd+F find bar — native macOS find bar for in-text search
• Process stderr highlighted in red (system messages are not colored)
• Auto-scroll toggle — follows new output when enabled, disables when you scroll up
• Font size — Cmd+Plus/Minus/0 to adjust, persisted in settings
• Word wrap toggle — in the toolbar menu, persisted in settings
• Clear button and Copy/Export in the toolbar menu
• Horizontal scrolling when word wrap is off
• Snapshot picker — when viewing logs from the Failure History tab, a dropdown lets you jump between different failure snapshots

Log row context menu

Right-click any log row for:

• Copy Line — the full formatted entry (timestamp, origin, message)
• Copy Message — just the message text
• Open URL — when the line contains a URL, open it in your browser
• Filter to This Source — scope the view to the entry’s origin
• Filter to This Severity — scope to the entry’s severity and above
• Star — bookmark the entry

(The log view is a high-performance list without a row-selection model, so these are mouse-only — there are no keyboard accelerators.)

See Working with Projects for more details.

JSON Output

corral logs --json

Each entry includes: id, timestamp, project_id, project_name, stream (stdout/stderr), origin (Corral/Process/Caddy/Dns), and message.