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:

• Monospaced display with timestamps
• Stderr entries highlighted in red
• Search/filter input
• Auto-scroll toggle (pin icon) to follow new output
• Clear button to reset the view
• Text selection for copying

See Working with Projects for more details.

JSON Output

corral logs --json

Each entry includes: timestamp, project_id, project_name, stream (stdout/stderr), and message.