Install via Docker

Use this method when Docker is already running on the host, or when you want to run the agent as a sidecar container.

The examples below use Vault as the log source.

Before you start

Get your entity credentials from the Logystera dashboard: Entities → your entity → Credentials.

---

1. Create a working directory

mkdir /opt/logystera-agent && cd /opt/logystera-agent

2. Create .env

cat > .env << 'EOF'
LOGYSTERA_GATEWAY_URL=https://gateway.logystera.com/v1/ingest

LOGYSTERA_ENTITY_TOKEN=your-entity-token-here
LOGYSTERA_ENTITY_SECRET=your-entity-secret-here

LOGYSTERA_CLIENT_ID=vault-prod-agent
LOGYSTERA_CUSTOMER_ID=your-org-name
LOGYSTERA_CLUSTER_ID=prod-cluster
LOGYSTERA_NODE_ID=vault-node-1
LOGYSTERA_ENVIRONMENT=production

HOST_VAULT_LOG_DIR=/var/log/vault
LOGYSTERA_LOG_PATH=/var/log/vault/audit.log
EOF

Set LOGYSTERA_CLIENT_ID and LOGYSTERA_NODE_ID to identify this specific node.

3. Create docker-compose.yml

services:
  agent:
    image: registry.gitlab.com/logystera/forwarder:latest
    container_name: logystera-agent
    restart: unless-stopped
    environment:
      - LOGYSTERA_GATEWAY_URL=${LOGYSTERA_GATEWAY_URL}
      - LOGYSTERA_ENTITY_TOKEN=${LOGYSTERA_ENTITY_TOKEN}
      - LOGYSTERA_ENTITY_SECRET=${LOGYSTERA_ENTITY_SECRET}
      - LOGYSTERA_CLIENT_ID=${LOGYSTERA_CLIENT_ID}
      - LOGYSTERA_CUSTOMER_ID=${LOGYSTERA_CUSTOMER_ID}
      - LOGYSTERA_CLUSTER_ID=${LOGYSTERA_CLUSTER_ID}
      - LOGYSTERA_NODE_ID=${LOGYSTERA_NODE_ID}
      - LOGYSTERA_ENVIRONMENT=${LOGYSTERA_ENVIRONMENT}
      - LOGYSTERA_LOG_PATH=${LOGYSTERA_LOG_PATH}
    volumes:
      - ${HOST_VAULT_LOG_DIR}:/var/log/vault:ro
      - logystera-agent-data:/var/log/logystera-agent
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  logystera-agent-data:

The logystera-agent-data volume persists the position file and delivery buffer across container restarts.

4. Start the agent

docker compose up -d

5. Verify

docker compose ps
docker compose logs -f agent

A successful start looks like:

logystera_gateway: starting output to https://gateway.logystera.com/v1/ingest
logystera_gateway: batch abc123 sent (12 events)

---

File permissions

The container runs as root by default. If your audit log is restricted to a specific group, make it world-readable:

chmod o+r /var/log/vault/audit.log

---

Kubernetes sidecar

See CI/CD & Automation for a full Kubernetes sidecar example with Vault.