Skip to main content
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)

​
Architecture

Each edge location runs:

​
Quick Start

​
1. Create an API Key

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

docker run -d \
  --name logfleet-agent \
  --restart unless-stopped \
  -e LOGFLEET_API_KEY=lf_prod_your_api_key \
  -e LOGFLEET_API_URL=https://api.logfleet.io \
  -e AGENT_NAME=edge-location-01 \
  -v /var/log:/var/log:ro \
  -v logfleet-data:/data \
  logfleet/edge-agent:latest

​
3. Verify Connection

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

VariableRequiredDefaultDescription
LOGFLEET_API_KEYYes-API key for authentication
LOGFLEET_API_URLYes-LogFleet API endpoint
AGENT_NAMEYes-Unique name for this agent
LOG_PATHSNo/var/logComma-separated paths to monitor
HEARTBEAT_INTERVALNo30sHeartbeat frequency
METRICS_INTERVALNo60sMetrics push frequency
CONFIG_SYNC_INTERVALNo60sConfig sync frequency
LOKI_RETENTIONNo7dLocal log retention period
LOKI_MAX_SIZENo10GBMaximum local storage

​
Docker Compose

For production deployments, use Docker Compose: 
version: '3.8'

services:
  logfleet-agent:
    image: logfleet/edge-agent:latest
    restart: unless-stopped
    environment:
      LOGFLEET_API_KEY: ${LOGFLEET_API_KEY}
      LOGFLEET_API_URL: https://api.logfleet.io
      AGENT_NAME: ${HOSTNAME:-edge-agent}
      LOG_PATHS: /var/log,/app/logs
      LOKI_RETENTION: 14d
      LOKI_MAX_SIZE: 50GB
    volumes:
      - /var/log:/var/log:ro
      - /app/logs:/app/logs:ro
      - logfleet-data:/data
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  logfleet-data:

​
Kubernetes

For Kubernetes deployments: 
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: logfleet/edge-agent:latest
          env:
            - name: LOGFLEET_API_KEY
              valueFrom:
                secretKeyRef:
                  name: logfleet-secrets
                  key: api-key
            - name: LOGFLEET_API_URL
              value: "https://api.logfleet.io"
            - name: AGENT_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
          volumeMounts:
            - name: varlog
              mountPath: /var/log
              readOnly: true
            - name: data
              mountPath: /data
          resources:
            requests:
              memory: "256Mi"
              cpu: "100m"
            limits:
              memory: "512Mi"
              cpu: "500m"
      volumes:
        - name: varlog
          hostPath:
            path: /var/log
        - name: data
          emptyDir:
            sizeLimit: 10Gi

​
Multiple Log Sources

Configure Vector to collect from multiple sources: 
# /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: 
curl -X GET https://api.logfleet.io/api/v1/dashboard/agent-health \
  -H "Authorization: Bearer $TOKEN"

​
Troubleshooting

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

​
Security Best Practices

Minimal Permissions

Only grant the API key permissions the agent actually needs.

Rotate Keys

Periodically rotate API keys and revoke old ones.

Network Isolation

Restrict agent network access to only LogFleet endpoints.

Read-Only Mounts

Mount log directories as read-only to prevent accidental writes.