orbforge · joshhardy · Aug 10, 2026
@@ -13,6 +13,7 @@ The Orb platform supports a range of deployment options and is highly configurab
 
 * [Set up Orb Cloud Analytics](/docs/orb-cloud#pro-plan-quickstart) - view, manage, and analyze your data in the cloud
 * [Set up Local Analytics](/docs/deploy-and-configure/local-analytics) - host your own Orb analytics dashboard
+* [Pre-configure an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install) - have sensors link and configure themselves on first start, on any platform
 * [Link Orbs with Deployment Tokens](/docs/deploy-and-configure/deployment-tokens) - configure and link Orbs at scale
 * [Windows & macOS MDM](/docs/deploy-and-configure/mdm) - easily deploy to corporate laptops or POS systems
 * [Guest Orbs](/docs/deploy-and-configure/guest-orbs) - easily link any Orb to your account with Guest Orbs

@@ -37,6 +37,10 @@ Deployment Tokens can be utilized to easily link Orbs to your Space and ensure t
 4. [Utilizing Mobile Device Management (MDM) tools for Windows and macOS](/docs/deploy-and-configure/deployment-tokens#using-mdm)
 
 :::tip
+Setting a token before the Orb ever starts is the recommended way to deploy sensors at scale. For the exact usage on each platform, see [Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install).
+:::
+
+:::info
 If you are using Orb as an individual with a handful of Orbs to manage, Deployment Tokens are not necessary for Linking or Configuration, as you may use other options such as logging into the application, discovery from another logged in Orb application, or using the CLI. See [Linking an Orb to your account](/docs/orb-app/linking-orb-to-account) for more details.
 :::
 
@@ -63,26 +67,32 @@ Your Orb is now linked to your Space! If you receive an error, the Orb is likely
 
 The environment variable `ORB_DEPLOYMENT_TOKEN` can be used to set the Deployment Token and link an Orb with your Space.
 
-:::warning
-As macOS apps run in restricted sandboxes, they do not have access to your shell environment. Therefore, using an environment variable does not function for the macOS app. The Orb macOS binary, Docker images, and Homebrew install options all support environment variables.
-:::
-
 You can simply insert the environment variable before running `orb sensor`:
 
 ```bash
 ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678 orb sensor
 ```
 
-Alternatively, you can export the environment variable to make it available to your shell and Orb.
+:::warning
+This only works when you launch the sensor yourself. In most real deployments Orb runs as a service, and service managers do not inherit your shell environment. Setting the variable in your shell or exporting it from `.bashrc` will have no effect on the running Orb. The variable has to go in the config file that your platform's service reads.
+:::
 
-```bash
-export ORB_DEPLOYMENT_TOKEN=orb-dt1-yourdeploymenttoken678
-```
+**[Pre-configuring an Orb at install time](/docs/deploy-and-configure/preconfigure-at-install)** lists that file for every supported platform:
 
-Adding this line to your shell's configuration is outside of the scope of this document.
+| Platform | Where `ORB_DEPLOYMENT_TOKEN` goes |
+| -------- | --------------------------------- |
+| Ubuntu, Debian, Raspberry Pi OS, RHEL/Fedora/CentOS, Arch | [`/etc/default/orb`](/docs/deploy-and-configure/preconfigure-at-install#linux-with-systemd) |
+| Alpine and other OpenRC systems | [`/etc/conf.d/orb`](/docs/deploy-and-configure/preconfigure-at-install#alpine-linux-and-other-openrc-systems) |
+| OpenWrt, GL.iNet | [`/etc/config/orb`](/docs/deploy-and-configure/preconfigure-at-install#openwrt) |
+| Docker, Synology, QNAP, Firewalla, Proxmox | [container `environment:`](/docs/deploy-and-configure/preconfigure-at-install#docker) |
+| Podman | [quadlet `Environment=`](/docs/deploy-and-configure/preconfigure-at-install#podman) |
+| Windows | [service registry key or installer flag](/docs/deploy-and-configure/preconfigure-at-install#windows) |
+| macOS | [MDM profile, or a token file for Homebrew](/docs/deploy-and-configure/preconfigure-at-install#macos) |
+| MikroTik RouterOS | [app environment settings](/docs/deploy-and-configure/preconfigure-at-install#mikrotik-routeros) |
+| Cisco IOx | [`package.yaml`](/docs/deploy-and-configure/preconfigure-at-install#cisco-iox) |
 
-:::tip
-If you're unsure how to add ORB_DEPLOYMENT_TOKEN to your shell's configuration file and source it, an AI chatbot can walk you through this task.
+:::warning
+As macOS apps run in restricted sandboxes, they do not have access to your shell environment. Therefore, using an environment variable does not function for the macOS app. The Orb macOS binary, Docker images, and Homebrew install options all support environment variables.
 :::
 
 ### Using a .txt file
@@ -98,6 +108,8 @@ echo "orb-dt1-yourdeploymenttoken678" > ~/.config/orb/deployment_token.txt
 
 Ensure you replace the deployment token and specify the correct configuration directory for your system. Orb will utilize the Deployment Token in the text file on the next run.
 
+Note that the file must live in the configuration directory of the user the Orb *service* runs as, which is often not your own user. This is the recommended approach on platforms with no service environment file, such as [FreeBSD](/docs/deploy-and-configure/preconfigure-at-install#freebsd) and [Homebrew on macOS](/docs/deploy-and-configure/preconfigure-at-install#macos).
+
 ### Using MDM
 
 Mobile Device Managment (MDM) systems can be used to deploy Orb at scale on Windows and macOS, and ensure the Orbs are linked to your Space. Details for using Deployment Tokens with MDM solutions are contained within the guides in the [MDM](/docs/deploy-and-configure/mdm) section.