Logging

Corral captures logs from every running project and from infrastructure services (DNS and proxy). You can view, search, and stream logs from the CLI or the macOS app.

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:

[2025-03-24 14:32:01] my-worker        | Ready on http://localhost:8787
[2025-03-24 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

Logs are persisted to disk in ~/.corral/logs/, with one file per project. This means logs survive app restarts — when Corral starts, it reloads the persisted history.

Log files are automatically rotated when they exceed 5 MB. During rotation, the older half is trimmed and the most recent entries are kept.

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

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
• 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

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.