Warning

This project is less actively maintained as I no longer have NixOS machines running Fleet. It is however setup with Renovate and ./update.sh in CI to try and automatically keep things up to date.

Once NixOS/nixpkgs#525702 is merged prefer using Fleet directly from nixpkgs. See also fleetdm/fleet#7319 (comment)

fleet-nixos

Fleet Orbit and Fleet Desktop integration for NixOS, packaged as a Nix flake.

Overview

This repository provides NixOS modules and packages for deploying Fleet Orbit and Fleet Desktop on NixOS systems. It builds the latest releases from FleetDM’s GitHub, applies custom patches for Nix compatibility, and exposes a flexible module for configuration.

Features

• Packages: Builds and provides orbit and fleet-desktop binaries.
• NixOS Module: Easily enable and configure Fleet Orbit and Fleet Desktop via services.orbit.
• Systemd Integration: Sets up system and user services for Orbit and Fleet Desktop.
• Custom Patches: Adds extra flags for NixOS compatibility (see below).
• Update Script: Automates updating to the latest Fleet Orbit release.

Installation

1. Add the flake as an input:

   inputs.fleet-nix = {
     url = "github:adamcik/fleet-nixos";
     inputs.nixpkgs.follows = "nixpkgs";
   };

2. Import the module in your NixOS configuration:

   imports = [
     inputs.fleet-nix.nixosModules.fleet-nixos
   ];

Configuration

Enable the service and configure options under services.orbit. You must set either enrollSecret or enrollSecretPath.

Example Configuration

services.orbit = {
  enable = true;
  fleetUrl = "https://your-fleet.example.com";
  # WARNING: use enrollSecretPath for secrets outside nix-store
  enrollSecret = "your-enroll-secret";
  debug = true;
  devMode = false;
  hostIdentifier = "uuid";
  enableScripts = false;
  fleetCertificate = "/etc/ssl/certs/ca-bundle.crt";
  fleetDesktopAlternativeBrowserHost = null;
  fleetManagedHostIdentityCertificate = false;
  endUserEmail = null;
  insecure = false;
};

Configuration Options and Environment Variables

Option	Description
enable	Enable Fleet Orbit systemd service
fleetUrl	Base URL of the Fleet server (ORBIT_FLEET_URL)
enrollSecret	Enroll secret for Fleet server (ORBIT_ENROLL_SECRET)
enrollSecretPath	Path to enroll secret file (ORBIT_ENROLL_SECRET_PATH)
fleetCertificate	Path to Fleet server certificate chain (ORBIT_FLEET_CERTIFICATE)
debug	Enable debug logging (ORBIT_DEBUG)
devMode	Enable development mode (ORBIT_DEV_MODE)
hostIdentifier	Host identifier mode (e.g., "uuid") (ORBIT_HOST_IDENTIFIER)
enableScripts	Enable script execution (ORBIT_ENABLE_SCRIPTS)
fleetDesktopAlternativeBrowserHost	Alternative browser host for Fleet Desktop (ORBIT_FLEET_DESKTOP_ALTERNATIVE_BROWSER_HOST)
fleetManagedHostIdentityCertificate	Use TPM-backed key for Fleet EE (requires license) (ORBIT_FLEET_MANAGED_HOST_IDENTITY_CERTIFICATE)
endUserEmail	End user email (experimental) (ORBIT_END_USER_EMAIL)
insecure	Disable TLS certificate verification (ORBIT_INSECURE)

Design Decisions

Some Orbit flags and environment variables are hardcoded or omitted for NixOS compatibility:

• Updates: All update-related flags are omitted/hardcoded because NixOS manages packages declaratively. Orbit’s auto-update logic is disabled.
• Keystore: Always disabled for NixOS to avoid storing secrets in OS-specific keystores.
• Paths: State, logs, and osquery DB paths are hardcoded for security and consistency.
• Channels: Update channels are not exposed; updates are managed by Nix, not Orbit.
• Deprecated/Platform-specific flags: Omitted as not relevant for NixOS.
• NixOS-specific flags: Extra flags are added via patches to ensure correct binary usage, log placement, and Fleet Desktop integration.

Systemd Services

• systemd.services.orbit: Runs the Orbit agent as a system service.
• systemd.user.services.fleet-desktop: Runs Fleet Desktop as a user service for graphical sessions.

NOTE: Orbit does not log everything to journald. Check /var/log/orbit/ for logs.

Patches

Patches in this repo add extra flags and functionality to Orbit for NixOS compatibility:

• orbit-nixos.patch: Patches Orbit's script execution to automatically replace common shebangs (like #!/bin/bash) with NixOS-style paths (#!/run/current-system/sw/bin/bash) before execution.
• osqueryd-path-override.patch: Adds NIX_ORBIT_OSQUERYD_PATH to allow overriding the osqueryd binary path, ensuring the version from the Nix store is used.
• osquery-log-path.patch: Adds NIX_ORBIT_OSQUERY_LOG_PATH to ensure osquery logs are written to /var/log/orbit/osquery/ instead of the root directory.
• scripts-nixos.patch: Relaxes Orbit's shebang validation to allow NixOS-specific paths and /usr/bin/env interpreters in scripts.

These patches ensure that Fleet Orbit works correctly in the read-only and non-standard environment of NixOS.

Development

Running Checks

To run all checks (formatting and package builds) locally, use:

nix flake check
nix flake check ./dev

This is the same command used in CI to ensure the repository is in a good state.

Cachix

CI pushes build outputs to the public fleet-nixos Cachix cache. The development flake is configured to use it:

nixConfig = {
  extra-substituters = ["https://fleet-nixos.cachix.org"];
  extra-trusted-public-keys = ["fleet-nixos.cachix.org-1:WuxM+Kqv8GoWP+kTmxHBUk9qVXvjvrYzoG17LtqJ4xc="];
};

GitHub Actions requires CACHIX_AUTH_TOKEN to push to the cache.

When using direnv, use the development flake and accept its cache configuration:

use flake ./dev --accept-flake-config

Formatting

This project uses alejandra for formatting Nix files. You can format the entire project with:

nix fmt ./dev

Updating Fleet Orbit

To update to the latest Fleet Orbit release, run:

nix-update orbit --flake --use-update-script

This will update the version, commit, and date in pkgs/default.nix.

Patch workflow

Patch files in patches/ should be treated as exported commits from a Fleet checkout, not hand-edited long-term.

1. Materialize a patch branch in ../fleet from local patch files:

   ./import-patches.sh --base-tag orbit-v1.54.0 --branch orbit-nixos-patches

   This applies each patches/NNNN-*.patch file in lexical order and creates one commit per patch on top of the base tag.

2. Rebase that branch in ../fleet onto a newer Orbit tag as needed.

3. Export the rebased commit range back into patch files:

   ./export-patches.sh --base orbit-v1.54.0 --head orbit-nixos-patches

   This writes patches/NNNN-*.patch (one per commit), where each filename is derived from the first line of the commit message.

This keeps patches reproducible and makes upstream churn easier to manage.

Fleet Desktop

Fleet Desktop is enabled as a user service when Orbit is enabled. It uses the same configuration and integrates with graphical sessions.

Troubleshooting & Tips

• Required: You must set either enrollSecret or enrollSecretPath.
• Debugging: Set debug = true for verbose logs.
• Secrets: Use enrollSecretPath with sops-nix for secure secret management.
• Logs: Check /var/log/orbit/ for logs.

---

For more details on Orbit configuration, see orbit.go upstream.