Skip to content

Install the Agent

The Noctuary Agent is a single statically-linked binary (or Docker image) that runs on your infrastructure alongside your application stack.

docker-compose.yml
services:
  noctuary-agent:
    image: ghcr.io/dbrimley-noctuary/noctuary-agent:latest
    command: ["-config", "/etc/noctuary/agent.yaml"]
    volumes:
      - ./agent.yaml:/etc/noctuary/agent.yaml:ro
    ports:
      - "4318:4318"   # OTLP/HTTP receiver
    environment:
      - NOCTUARY_API_KEY=noc_ingest_your_key_here
      - NOCTUARY_ENDPOINT=https://api.noctuary.io
    restart: unless-stopped

Binary (Linux/amd64)

curl -fsSL https://github.com/dbrimley-noctuary/noctuary/releases/latest/download/noctuary-agent-linux-amd64 \
  -o /usr/local/bin/noctuary-agent
chmod +x /usr/local/bin/noctuary-agent
noctuary-agent -version

Agent configuration

Create agent.yaml in the same directory:

agent.yaml
upstream:
  destination: http
  endpoint: ${NOCTUARY_ENDPOINT}   # https://api.noctuary.io

auth:
  api_key: ${NOCTUARY_API_KEY}     # noc_ingest_...

telemetry:
  otlp:
    http_listen: ":4318"           # OTLP/HTTP receiver port

plugins:
  argocd:
    enabled: true
  kubernetes:
    enabled: true
  postgres:
    enabled: true

fingerprint:
  confidence_threshold: 0.5        # discard signals below this confidence

Environment variables are expanded at startup — you can reference them anywhere in the config with ${VAR_NAME}.

Configure your OTel Collector

Point your existing OpenTelemetry Collector at the agent's OTLP/HTTP endpoint:

otelcol-config.yml
exporters:
  otlphttp/noctuary:
    endpoint: http://noctuary-agent:4318
    encoding: json
    compression: none

service:
  pipelines:
    logs:
      receivers: [filelog]
      processors: [resource]
      exporters: [otlphttp/noctuary, otlp]   # send to Noctuary AND your existing backend

The agent only processes log lines that match a vendor plugin pattern. All other lines pass through silently.

Verify the agent is running

The agent exposes a health endpoint:

curl http://localhost:4318/health
# {"status":"ok","version":"0.1.0"}

And registers itself with the Noctuary backend on startup. You should see it appear in the dashboard under Agents within a few seconds.

Supported platforms

Platform Status
Linux/amd64 Supported
Linux/arm64 Supported
Docker Supported
Kubernetes (DaemonSet) Supported
macOS Dev/testing only

Next step

Connect PagerDuty