> ## Documentation Index
> Fetch the complete documentation index at: https://docker-agent-tail.michaelscotello.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> A quick 5-minute tutorial to get docker-agent-tail working with your containers.

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

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
docker-agent-tail --names web-server,worker-app --follow
```

## Step 4: Filter Log Content

Use regex patterns to filter and mute specific log lines:

```bash theme={null}
# 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`):

```bash theme={null}
# 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:

<CodeGroup>
  ```json Plain text container output theme={null}
  {"ts":"2026-03-04T10:30:01.789Z","container":"web-server","stream":"stdout","message":"GET /api/users 200 12ms"}
  ```

  ```json Structured JSON (merged + level normalized) theme={null}
  {"ts":"2026-03-04T10:30:01.789Z","container":"api","stream":"stdout","level":"info","msg":"request completed","status":200}
  ```
</CodeGroup>

* **`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](/lnav) and use it to view the saved logs:

```bash theme={null}
docker-agent-tail lnav-install  # one-time setup
lnav logs/latest/combined.jsonl
```

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/cli-reference">
    Explore all available commands, flags, and options
  </Card>

  <Card title="Using with AI Agents" icon="robot" href="/agents">
    Learn how to use docker-agent-tail with Claude Code and Cursor
  </Card>
</CardGroup>