Device Onboarding

How to connect your edge devices to FleetManager and start transmitting data.

Prerequisites

• A FleetManager account with at least one customer
• Network access from the device to the FleetManager server (HTTPS, port 443)

Step 1: Create a Customer

If no customer exists yet, create one in the dashboard under Customer Management. The customer slug (e.g., my-company) identifies the customer in the API.

Step 2: Create an Ingest Token

1. Open Customer Management and select the customer
2. Click Create Token
3. Optionally set an expiration date
4. Copy the displayed token — it is shown only once

The token authorizes devices to submit data for this customer.

Step 3: Configure the Device

Option A: Python Client Library (recommended)

Install brinkhaustools and use the FleetMonitorClient:

from brinkhaustools.common.fleet.client import FleetMonitorClient

client = FleetMonitorClient(
    base_url="https://fleet.brinkhaus-gmbh.de",
    customer="my-company",
    machine="server-01",
    software="my-app",
    token="my-ingest-token",
    heartbeat_interval=60,
    version="1.0.0",
)

# Heartbeats are sent automatically in the background.
# Send diagnostics:
client.send_diagnostics([
    {"code": 1000, "message": "All OK", "severity": 0},
])

# Send status:
client.send_status("running", "Application running normally")

Option B: Direct HTTPS API

Send HTTP POST requests to the ingest endpoints:

POST /api/ingest/{customer}/{machine}/{software}/heartbeat
POST /api/ingest/{customer}/{machine}/{software}/diagnostics
POST /api/ingest/{customer}/{machine}/{software}/status

Header: Authorization: Bearer {token}

Heartbeat payload:

{
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "pid": 1234,
  "ips": ["10.0.0.5"]
}

Diagnostics payload:

{
  "diagnostics": [
    {"code": 1000, "message": "OK", "severity": 0}
  ]
}

Status payload:

{
  "status": "running",
  "message": "Application running",
  "snapshot": {"cpu": 45, "memory": 2048}
}

Option C: Security Agent

For security monitoring, install the FleetManager Security Agent. It automatically sends heartbeats and diagnostic messages through its modules.

Configuration in /etc/fleetmanager-security/config.yaml:

fleetmanager:
  base_url: https://fleet.brinkhaus-gmbh.de
  token: "my-ingest-token"
  customer: "my-company"
  machine: "server-01"

Step 4: Verify Connection

After the first heartbeat, the device automatically appears in the dashboard. If it doesn’t:

1. Check the Ingest Rejection Log in the dashboard — rejected requests are logged with the rejection reason
2. Verify that the token is valid and not expired
3. Check network connectivity to the FleetManager server

Slug Format

Customer, machine, and software slugs must follow the format ^[a-z0-9][a-z0-9-]*$:

• Only lowercase letters, digits, and hyphens
• Must start with a letter or digit
• Examples: server-01, my-app, brinkhaus-gmbh

Automatic Registration

New machines and software instances are created automatically on first ingest (UPSERT pattern). No manual registration is required.