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)

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

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
API_KEYYes-API key for cloud authentication
CLOUD_URLNohttp://host.docker.internal:8080LogFleet cloud API endpoint
AGENT_NAMENoedge-agent-1Unique name for this agent
LOKI_URLNohttp://loki:3100Local Loki endpoint
HEARTBEAT_INTERVALNo30sHeartbeat frequency
CONFIG_SYNC_INTERVALNo5mConfig sync frequency

​
Docker Compose

For production deployments with local Loki storage: 
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: 
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: 
# /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.