Skip to main content

​
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: 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

​
Next Steps

CLI Reference

Explore all available commands, flags, and options

Using with AI Agents

Learn how to use docker-agent-tail with Claude Code and Cursor