Getting Started

Step 1: Start Some Containers

First, make sure you have Docker running with at least one container. If you don’t have any running, start a quick test container:

# Start a simple web server
docker run -d --name web-server nginx

# Start a background worker
docker run -d --name worker-app busybox sh -c "while true; do echo 'working...'; sleep 5; done"

Step 2: Tail All Logs

Run docker-agent-tail with the --all flag to discover and tail all running containers:

docker-agent-tail --all --follow

You’ll see logs from both containers streaming in real-time with timestamps and container names.

Step 3: Filter Specific Containers

Target specific containers using the --names flag:

docker-agent-tail --names web-server,worker-app --follow

Step 4: Filter Log Content

Use regex patterns to filter and mute specific log lines:

# Exclude lines matching a pattern
docker-agent-tail --all --exclude 'health.*check' --follow

# Mute specific containers from terminal (still saved to log files)
docker-agent-tail --all --mute 'worker-app' --follow

Step 5: Save to Files

Logs are automatically saved to the ./logs directory (configurable with --output):

# Uses default output directory ./logs
docker-agent-tail --all --follow

# Or specify a custom directory
docker-agent-tail --all --output ./debug-logs --follow

This creates a timestamped session directory with per-container .jsonl files and a combined.jsonl. A latest symlink always points to the most recent session.

Understanding Log Output

Log files use JSON Lines format (.jsonl), with one JSON object per line:

{"ts":"2026-03-04T10:30:01.789Z","container":"web-server","stream":"stdout","message":"GET /api/users 200 12ms"}

{"ts":"2026-03-04T10:30:01.789Z","container":"api","stream":"stdout","level":"info","msg":"request completed","status":200}

ts: ISO 8601 timestamp with nanosecond precision
container: Container name
stream: stdout or stderr
level: Normalized log level (when detected from structured JSON)

For interactive log exploration, install lnav and use it to view the saved logs:

docker-agent-tail lnav-install  # one-time setup
lnav logs/latest/combined.jsonl

Get Started

Reference

Help

Step 1: Start Some Containers

Step 2: Tail All Logs

Step 3: Filter Specific Containers

Step 4: Filter Log Content

Step 5: Save to Files

Understanding Log Output

Next Steps

CLI Reference

Using with AI Agents

​Step 1: Start Some Containers

​Step 2: Tail All Logs

​Step 3: Filter Specific Containers

​Step 4: Filter Log Content

​Step 5: Save to Files

​Understanding Log Output

​Next Steps

CLI Reference

Using with AI Agents

Step 1: Start Some Containers

Step 2: Tail All Logs

Step 3: Filter Specific Containers

Step 4: Filter Log Content

Step 5: Save to Files

Understanding Log Output

Next Steps