> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logfleet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Edge Agent Setup

> Deploy and configure LogFleet edge agents

This guide covers deploying LogFleet edge agents on your distributed devices. Edge agents collect logs locally, extract metrics, and stream logs on-demand.

## Prerequisites

* Docker installed on your edge device
* Network connectivity to `api.logfleet.io`
* An API key with edge permissions (see [Authentication](/authentication))

## Quick Start

### 1. Create an API Key

```bash theme={null}
export TOKEN="your-jwt-token"

curl -X POST https://api.logfleet.io/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Edge Agent - Location 1",
    "permissions": ["edge:register", "edge:heartbeat", "edge:metrics", "edge:stream"]
  }'
```

Save the `raw_key` from the response.

### 2. Deploy with Docker

```bash theme={null}
docker run -d \
  --name logfleet-agent \
  --restart unless-stopped \
  -e API_KEY=$API_KEY \
  -e CLOUD_URL=https://api.logfleet.io \
  -e AGENT_NAME=edge-location-01 \
  -p 9880:9880 \
  -p 514:5140/udp \
  ghcr.io/sadhiappan/logfleet-agent:latest
```

This exposes:

* **Port 9880**: HTTP JSON log input
* **Port 514**: Syslog UDP input

### 3. Verify Connection

```bash theme={null}
curl -X GET https://api.logfleet.io/api/v1/agents \
  -H "Authorization: Bearer $TOKEN"
```

You should see your agent listed with status `online`.

## Configuration Options

### Environment Variables

| Variable               | Required | Default                            | Description                      |
| ---------------------- | -------- | ---------------------------------- | -------------------------------- |
| `API_KEY`              | Yes      | -                                  | API key for cloud authentication |
| `CLOUD_URL`            | No       | `http://host.docker.internal:8080` | LogFleet cloud API endpoint      |
| `AGENT_NAME`           | No       | `edge-agent-1`                     | Unique name for this agent       |
| `LOKI_URL`             | No       | `http://loki:3100`                 | Local Loki endpoint              |
| `HEARTBEAT_INTERVAL`   | No       | `30s`                              | Heartbeat frequency              |
| `CONFIG_SYNC_INTERVAL` | No       | `5m`                               | Config sync frequency            |

### Docker Compose

For production deployments with local Loki storage:

```yaml theme={null}
version: '3.8'

services:
  logfleet-agent:
    image: ghcr.io/sadhiappan/logfleet-agent:latest
    restart: unless-stopped
    environment:
      - API_KEY=${API_KEY}
      - CLOUD_URL=https://api.logfleet.io
      - AGENT_NAME=${HOSTNAME:-edge-agent}
    ports:
      - "9880:9880"
      - "514:5140/udp"
    volumes:
      - loki-data:/loki
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  loki-data:
```

### Kubernetes

For Kubernetes deployments:

```yaml theme={null}
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: logfleet-agent
  namespace: logfleet
spec:
  selector:
    matchLabels:
      app: logfleet-agent
  template:
    metadata:
      labels:
        app: logfleet-agent
    spec:
      containers:
        - name: agent
          image: ghcr.io/sadhiappan/logfleet-agent:latest
          env:
            - name: API_KEY
              valueFrom:
                secretKeyRef:
                  name: logfleet-secrets
                  key: api-key
            - name: CLOUD_URL
              value: "https://api.logfleet.io"
            - name: AGENT_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
          ports:
            - containerPort: 9880
              name: http
            - containerPort: 5140
              protocol: UDP
              name: syslog
          resources:
            requests:
              memory: "256Mi"
              cpu: "100m"
            limits:
              memory: "512Mi"
              cpu: "500m"
```

## Multiple Log Sources

Configure Vector to collect from multiple sources:

```toml theme={null}
# /etc/logfleet/vector.toml

[sources.syslog]
type = "file"
include = ["/var/log/syslog", "/var/log/messages"]

[sources.nginx]
type = "file"
include = ["/var/log/nginx/*.log"]

[sources.application]
type = "file"
include = ["/app/logs/*.log"]

[sources.docker]
type = "docker_logs"
```

## Offline Operation

Edge agents are designed to work offline:

1. **Local Storage**: Logs are stored in Loki with configurable retention
2. **Metrics Buffer**: Metrics are buffered locally if cloud is unreachable
3. **Auto-Retry**: Automatic reconnection when connectivity is restored
4. **No Data Loss**: Buffered data is pushed when connection resumes

## Monitoring Agent Health

### Dashboard

View agent status in the LogFleet dashboard:

* Online/Offline status
* Last heartbeat time
* Metrics throughput
* Storage usage

### API

Check agent health programmatically:

```bash theme={null}
curl -X GET https://api.logfleet.io/api/v1/dashboard/agent-health \
  -H "Authorization: Bearer $TOKEN"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent not appearing in dashboard">
    1. Check the API key has `edge:register` permission
    2. Verify network connectivity: `curl https://api.logfleet.io/health`
    3. Check agent logs: `docker logs logfleet-agent`
    4. Ensure `AGENT_NAME` is unique within your organization
  </Accordion>

  <Accordion title="Agent shows as offline">
    1. Verify heartbeat interval isn't too long
    2. Check for network issues between agent and cloud
    3. Ensure the API key hasn't been revoked
    4. Check agent logs for errors
  </Accordion>

  <Accordion title="Logs not appearing in streams">
    1. Verify log paths are correctly mounted
    2. Check file permissions (agent needs read access)
    3. Ensure log files are being written to
    4. Check Vector configuration for parsing errors
  </Accordion>

  <Accordion title="High memory usage">
    1. Reduce `LOKI_MAX_SIZE` to limit storage
    2. Decrease `LOKI_RETENTION` to delete older logs faster
    3. Check for log storms (high volume log generation)
    4. Consider filtering out verbose logs at the source
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Minimal Permissions" icon="shield">
    Only grant the API key permissions the agent actually needs.
  </Card>

  <Card title="Rotate Keys" icon="rotate">
    Periodically rotate API keys and revoke old ones.
  </Card>

  <Card title="Network Isolation" icon="network-wired">
    Restrict agent network access to only LogFleet endpoints.
  </Card>

  <Card title="Read-Only Mounts" icon="lock">
    Mount log directories as read-only to prevent accidental writes.
  </Card>
</CardGroup>