# Fleet Device Management

Fleet is an open-source platform for IT and security teams to manage thousands of computers across macOS, Windows, Linux, Chromebooks, and cloud infrastructure. Built on osquery and nanoMDM, Fleet provides vulnerability reporting, detection engineering, mobile device management (MDM), device health monitoring, posture-based access control, and software license management. The platform is designed for APIs, GitOps workflows, webhooks, YAML configuration, and supports deployments from hundreds to 400,000+ hosts.

Fleet offers a comprehensive REST API for automating device management tasks, including host inventory, software management, policy enforcement, MDM configuration, and security compliance. The platform supports both self-hosted and managed cloud deployments, with a free tier always available. Fleet integrates with enterprise tools like Snowflake, Splunk, GitHub Actions, Vanta, Elastic, Jira, and Zendesk, and works alongside security tools like CrowdStrike and SentinelOne.

## Authentication

All API requests require Bearer token authentication obtained via login or from the Fleet UI.

```bash
# Login to get API token
curl -X POST https://fleet.example.com/api/v1/fleet/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "your_password"
  }'

# Response includes token for subsequent requests
# {
#   "user": { "id": 1, "name": "Admin", "email": "admin@example.com", ... },
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
# }

# Use token in Authorization header for all API calls
curl https://fleet.example.com/api/v1/fleet/hosts \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## List Hosts

Retrieve paginated list of all enrolled hosts with optional filtering by status, team, policy, software, OS version, MDM status, and more.

```bash
# List hosts with pagination, filtering, and additional data
curl "https://fleet.example.com/api/v1/fleet/hosts?page=0&per_page=100&order_key=hostname&order_direction=asc&status=online&populate_software=true&populate_policies=true" \
  -H "Authorization: Bearer $TOKEN"

# Response
# {
#   "hosts": [
#     {
#       "id": 1,
#       "hostname": "macbook-pro.local",
#       "uuid": "392547dc-0000-0000-a87a-d701ff75bc65",
#       "platform": "darwin",
#       "os_version": "macOS 15.2",
#       "hardware_serial": "C0124FXASD6G",
#       "primary_ip": "192.168.1.100",
#       "status": "online",
#       "team_id": 1,
#       "team_name": "Engineering",
#       "gigs_disk_space_available": 174.98,
#       "mdm": {
#         "enrollment_status": "On (automatic)",
#         "name": "Fleet",
#         "encryption_key_available": true
#       },
#       "software": [...],
#       "policies": [...]
#     }
#   ],
#   "meta": { "has_next_results": true, "has_previous_results": false }
# }

# Filter by team, policy status, or software
curl "https://fleet.example.com/api/v1/fleet/hosts?team_id=1&policy_id=5&policy_response=failing" \
  -H "Authorization: Bearer $TOKEN"
```

## Get Host Details

Retrieve comprehensive details for a specific host including hardware info, MDM status, installed software, and policy compliance.

```bash
# Get host by ID
curl https://fleet.example.com/api/v1/fleet/hosts/1 \
  -H "Authorization: Bearer $TOKEN"

# Get host by identifier (hostname, UUID, or serial number)
curl "https://fleet.example.com/api/v1/fleet/hosts/identifier/C0124FXASD6G" \
  -H "Authorization: Bearer $TOKEN"

# Response includes full host details
# {
#   "host": {
#     "id": 1,
#     "hostname": "macbook-pro.local",
#     "platform": "darwin",
#     "os_version": "macOS 15.2",
#     "hardware_vendor": "Apple Inc.",
#     "hardware_model": "MacBookPro17,1",
#     "hardware_serial": "C0124FXASD6G",
#     "cpu_brand": "Apple M1",
#     "memory": 17179869184,
#     "gigs_disk_space_available": 174.98,
#     "mdm": {
#       "enrollment_status": "On (automatic)",
#       "encryption_key_available": true,
#       "name": "Fleet"
#     },
#     "batteries": [{ "health": "Normal", "cycle_count": 245 }],
#     "geolocation": { "city_name": "San Francisco", "country_iso": "US" }
#   }
# }
```

## Run Live Query

Execute ad-hoc SQL queries against hosts in real-time using osquery's distributed query system.

```bash
# Run a live query against specific hosts
curl -X POST https://fleet.example.com/api/v1/fleet/queries/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM system_info;",
    "selected": {
      "hosts": [1, 2, 3],
      "labels": [6]
    }
  }'

# Response with query results from each host
# {
#   "campaign": {
#     "id": 42,
#     "query": "SELECT * FROM system_info;",
#     "status": 0,
#     "user_id": 1
#   },
#   "results": [
#     {
#       "host_id": 1,
#       "hostname": "macbook-pro.local",
#       "rows": [
#         {
#           "hostname": "macbook-pro.local",
#           "cpu_brand": "Apple M1",
#           "physical_memory": "17179869184"
#         }
#       ]
#     }
#   ]
# }

# Run query on a single host by ID
curl -X POST https://fleet.example.com/api/v1/fleet/hosts/1/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM users;"}'
```

## Policies

Create and manage compliance policies that check hosts against security requirements using osquery queries.

```bash
# Create a global policy
curl -X POST https://fleet.example.com/api/v1/fleet/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FileVault Enabled",
    "query": "SELECT 1 FROM filevault_status WHERE status = '\''FileVault is On.'\'';",
    "description": "Checks if FileVault disk encryption is enabled on macOS",
    "resolution": "Enable FileVault in System Preferences > Security & Privacy",
    "platform": "darwin",
    "critical": true
  }'

# Create a team policy with software install automation (Fleet Premium)
curl -X POST https://fleet.example.com/api/v1/fleet/teams/1/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zoom Installed",
    "query": "SELECT 1 FROM apps WHERE name = '\''zoom.us.app'\'';",
    "description": "Checks if Zoom is installed",
    "platform": "darwin",
    "software_title_id": 123
  }'

# List policies and their pass/fail counts
curl https://fleet.example.com/api/v1/fleet/policies \
  -H "Authorization: Bearer $TOKEN"

# Response
# {
#   "policies": [
#     {
#       "id": 1,
#       "name": "FileVault Enabled",
#       "passing_host_count": 450,
#       "failing_host_count": 12,
#       "critical": true
#     }
#   ]
# }
```

## Software Management

List software inventory, manage software packages, and deploy applications to hosts.

```bash
# List all software titles with vulnerability counts
curl "https://fleet.example.com/api/v1/fleet/software/titles?per_page=50&vulnerable=true" \
  -H "Authorization: Bearer $TOKEN"

# Response
# {
#   "software_titles": [
#     {
#       "id": 1,
#       "name": "Firefox",
#       "versions_count": 3,
#       "hosts_count": 245,
#       "vulnerabilities_count": 2,
#       "source": "apps"
#     }
#   ],
#   "count": 1523,
#   "counts_updated_at": "2024-01-15T10:30:00Z"
# }

# Upload a software package for deployment
curl -X POST https://fleet.example.com/api/v1/fleet/software/packages \
  -H "Authorization: Bearer $TOKEN" \
  -F "software=@/path/to/package.pkg" \
  -F "team_id=1" \
  -F "install_script=installer -pkg \"\$INSTALLER_PATH\" -target /" \
  -F "self_service=true"

# Install software on a specific host
curl -X POST https://fleet.example.com/api/v1/fleet/hosts/1/software/install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"software_title_id": 123}'
```

## MDM Configuration Profiles

Deploy and manage configuration profiles for macOS, iOS, iPadOS, and Windows hosts.

```bash
# Upload a macOS configuration profile
curl -X POST https://fleet.example.com/api/v1/fleet/configuration_profiles \
  -H "Authorization: Bearer $TOKEN" \
  -F "profile=@/path/to/profile.mobileconfig" \
  -F "team_id=1" \
  -F "labels_include_all=Engineering"

# Response
# { "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24" }

# List configuration profiles
curl "https://fleet.example.com/api/v1/fleet/configuration_profiles?team_id=1" \
  -H "Authorization: Bearer $TOKEN"

# Response
# {
#   "profiles": [
#     {
#       "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24",
#       "name": "Wi-Fi Settings",
#       "platform": "darwin",
#       "identifier": "com.example.wifi",
#       "labels_include_all": [{"name": "Engineering", "id": 5}]
#     }
#   ]
# }

# Delete a configuration profile
curl -X DELETE https://fleet.example.com/api/v1/fleet/configuration_profiles/954ec5ea-a334-4825-87b3-937e7e381f24 \
  -H "Authorization: Bearer $TOKEN"
```

## Labels

Create and manage dynamic and manual host labels for organizing and targeting hosts.

```bash
# Create a dynamic label using a query
curl -X POST https://fleet.example.com/api/v1/fleet/labels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Low Disk Space",
    "query": "SELECT 1 FROM disk_info WHERE free_space < 10737418240;",
    "description": "Hosts with less than 10GB free disk space",
    "platform": ""
  }'

# Create a manual label with specific hosts
curl -X POST https://fleet.example.com/api/v1/fleet/labels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Executive Laptops",
    "description": "C-Suite devices requiring special handling",
    "label_membership_type": "manual",
    "hosts": ["C0124FXASD6G", "D9876ABCDE1F"]
  }'

# List all labels
curl https://fleet.example.com/api/v1/fleet/labels \
  -H "Authorization: Bearer $TOKEN"

# Get hosts belonging to a label
curl https://fleet.example.com/api/v1/fleet/labels/6/hosts \
  -H "Authorization: Bearer $TOKEN"
```

## Scripts

Execute scripts on hosts for automation and remediation tasks.

```bash
# Add a script to Fleet
curl -X POST https://fleet.example.com/api/v1/fleet/scripts \
  -H "Authorization: Bearer $TOKEN" \
  -F "script=@/path/to/script.sh" \
  -F "team_id=1"

# Run a script on a specific host
curl -X POST https://fleet.example.com/api/v1/fleet/hosts/1/scripts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"script_id": 42}'

# Get script execution results
curl https://fleet.example.com/api/v1/fleet/scripts/results/abc123-execution-id \
  -H "Authorization: Bearer $TOKEN"

# Response
# {
#   "script_id": 42,
#   "host_id": 1,
#   "exit_code": 0,
#   "output": "Script executed successfully\n",
#   "runtime": 1.234
# }
```

## Fleet Configuration

Retrieve and update global Fleet server configuration including MDM settings, SSO, webhooks, and integrations.

```bash
# Get current configuration
curl https://fleet.example.com/api/v1/fleet/config \
  -H "Authorization: Bearer $TOKEN"

# Update configuration
curl -X PATCH https://fleet.example.com/api/v1/fleet/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_info": {
      "org_name": "Acme Corp",
      "org_logo_url": "https://example.com/logo.png"
    },
    "webhook_settings": {
      "vulnerabilities_webhook": {
        "enable_vulnerabilities_webhook": true,
        "destination_url": "https://webhook.example.com/vulnerabilities"
      }
    },
    "mdm": {
      "enable_disk_encryption": true,
      "macos_updates": {
        "minimum_version": "14.0",
        "deadline": "2024-03-01"
      }
    }
  }'
```

## Teams (Fleet Premium)

Manage teams to organize hosts and apply different configurations per team.

```bash
# Create a team
curl -X POST https://fleet.example.com/api/v1/fleet/teams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Engineering department workstations"
  }'

# Update team agent options
curl -X PATCH https://fleet.example.com/api/v1/fleet/teams/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_options": {
      "config": {
        "options": {
          "distributed_interval": 10,
          "logger_tls_period": 10
        }
      }
    }
  }'

# Transfer hosts to a team
curl -X POST https://fleet.example.com/api/v1/fleet/hosts/transfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": 1,
    "hosts": [1, 2, 3, 4, 5]
  }'

# Get team enroll secrets
curl https://fleet.example.com/api/v1/fleet/teams/1/secrets \
  -H "Authorization: Bearer $TOKEN"
```

## Activities

Retrieve audit log of activities performed in Fleet for security and compliance monitoring.

```bash
# List recent activities with pagination
curl "https://fleet.example.com/api/v1/fleet/activities?page=0&per_page=50&order_key=created_at&order_direction=desc" \
  -H "Authorization: Bearer $TOKEN"

# Response
# {
#   "activities": [
#     {
#       "id": 1234,
#       "created_at": "2024-01-15T10:30:00Z",
#       "type": "installed_software",
#       "actor_full_name": "Jane Admin",
#       "actor_email": "jane@example.com",
#       "details": {
#         "host_id": 42,
#         "host_display_name": "macbook-pro.local",
#         "software_title": "Zoom",
#         "status": "installed"
#       }
#     }
#   ],
#   "meta": { "has_next_results": true, "has_previous_results": false }
# }

# Filter by activity type
curl "https://fleet.example.com/api/v1/fleet/activities?activity_type=edited_policy" \
  -H "Authorization: Bearer $TOKEN"
```

## Vulnerabilities

Query and manage vulnerability data from software inventory scans.

```bash
# List all vulnerabilities
curl "https://fleet.example.com/api/v1/fleet/vulnerabilities?page=0&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

# Response
# {
#   "vulnerabilities": [
#     {
#       "cve": "CVE-2024-1234",
#       "hosts_count": 45,
#       "software_name": "OpenSSL",
#       "cvss_score": 9.8,
#       "epss_probability": 0.89,
#       "cisa_known_exploit": true,
#       "resolved_in_version": "3.0.12"
#     }
#   ],
#   "count": 234
# }

# Get vulnerability details
curl https://fleet.example.com/api/v1/fleet/vulnerabilities/CVE-2024-1234 \
  -H "Authorization: Bearer $TOKEN"

# List hosts affected by a specific CVE
curl "https://fleet.example.com/api/v1/fleet/hosts?vulnerability=CVE-2024-1234" \
  -H "Authorization: Bearer $TOKEN"
```

## MDM Commands

Send MDM commands to Apple and Windows devices for lock, wipe, and other device management actions.

```bash
# Lock a host
curl -X POST https://fleet.example.com/api/v1/fleet/hosts/1/lock \
  -H "Authorization: Bearer $TOKEN"

# Wipe a host (with options for Windows)
curl -X POST https://fleet.example.com/api/v1/fleet/hosts/1/wipe \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"disallow_proximity_unlock": true}'

# Get disk encryption key for a host
curl https://fleet.example.com/api/v1/fleet/hosts/1/encryption_key \
  -H "Authorization: Bearer $TOKEN"

# Response
# {
#   "encryption_key": {
#     "key": "XXXX-XXXX-XXXX-XXXX-XXXX-XXXX",
#     "updated_at": "2024-01-15T10:30:00Z"
#   }
# }

# List MDM commands for a host
curl https://fleet.example.com/api/v1/fleet/hosts/1/commands \
  -H "Authorization: Bearer $TOKEN"
```

## Server Configuration (YAML)

Fleet server configuration via environment variables or YAML config file for MySQL, Redis, and server settings.

```yaml
# fleet.yml - Server configuration
mysql:
  address: mysql.example.com:3306
  database: fleet
  username: fleet
  password_path: /run/secrets/mysql-password
  max_open_conns: 50
  max_idle_conns: 50

redis:
  address: redis.example.com:6379
  password: your_redis_password
  database: 0
  use_tls: true

server:
  address: 0.0.0.0:8080
  cert: /path/to/server.cert
  key: /path/to/server.key

logging:
  debug: false
  json: true
  result:
    plugin: firehose
    config:
      region: us-east-1
      result_stream: fleet-results
```

```bash
# Environment variable equivalents
export FLEET_MYSQL_ADDRESS=mysql.example.com:3306
export FLEET_MYSQL_DATABASE=fleet
export FLEET_MYSQL_USERNAME=fleet
export FLEET_MYSQL_PASSWORD=secret
export FLEET_REDIS_ADDRESS=redis.example.com:6379
export FLEET_SERVER_ADDRESS=0.0.0.0:8080
```

## GitOps Configuration (YAML)

Fleet supports GitOps workflows for managing configuration as code using YAML files and the `fleetctl gitops` command.

```yaml
# default.yml - Global configuration
org_settings:
  server_settings:
    server_url: https://fleet.example.com
  org_info:
    org_name: Acme Corporation
    contact_url: https://support.example.com

agent_options:
  config:
    options:
      distributed_interval: 10
      logger_tls_period: 10
      disable_distributed: false
    decorators:
      load:
        - SELECT uuid AS host_uuid FROM system_info;
        - SELECT hostname AS hostname FROM system_info;

labels:
  - name: Engineering
    description: Engineering department hosts
    query: SELECT 1 FROM system_info WHERE computer_name LIKE 'ENG-%';
    label_membership_type: dynamic

policies:
  - name: Disk Encryption Enabled
    query: SELECT 1 FROM disk_encryption WHERE encrypted = 1;
    description: Ensures disk encryption is enabled
    resolution: Enable FileVault on macOS or BitLocker on Windows
    platform: darwin,windows
    critical: true

controls:
  enable_disk_encryption: true
  macos_updates:
    minimum_version: "14.0"
    deadline: "2024-06-01"
  scripts:
    - path: ./scripts/install-updates.sh
```

```yaml
# teams/engineering.yml - Team-specific configuration
name: Engineering
team_settings:
  secrets:
    - secret: ABC123-ENROLL-SECRET

agent_options:
  path: ../lib/agent-options.yml

policies:
  - path: ../lib/policies/security.policies.yml
  - name: Developer Tools Installed
    query: SELECT 1 FROM apps WHERE name IN ('Xcode.app', 'Visual Studio Code.app');
    platform: darwin

software:
  packages:
    - path: ../software/vscode.package.yml
    - path: ../software/slack.package.yml
```

```bash
# Apply GitOps configuration
fleetctl gitops -f default.yml -f teams/engineering.yml
```

## Summary

Fleet provides a comprehensive REST API for enterprise device management across macOS, Windows, Linux, and mobile platforms. The primary use cases include automated vulnerability scanning and reporting, compliance policy enforcement with remediation automations, software deployment and patch management, MDM configuration profile distribution, real-time device querying with osquery, and integration with security tools and ticketing systems via webhooks.

Integration patterns typically involve authenticating with a service account token, using the hosts API to inventory and filter devices, deploying policies and software via teams, configuring MDM profiles for OS settings enforcement, and setting up webhooks for real-time alerts to SIEM/SOAR platforms. For infrastructure-as-code workflows, Fleet's GitOps support with `fleetctl` enables version-controlled configuration management, making it ideal for teams practicing DevOps and requiring audit trails for compliance. The platform scales from small deployments to enterprise environments with 400,000+ hosts.