Skip to main content
Forge for devices extends AI governance to managed Windows, macOS, and Linux devices. Its installed component, the Device Agent, automatically routes supported desktop, browser, developer API, and MCP traffic through your organization’s Forge Gateways. It also reports device health and discovers local AI products and configuration. Use agentless network routing when traffic already passes through a connected firewall, SASE platform, or secure web gateway. Deploy Forge for devices for off-network coverage, local applications, and device-level attribution. The two approaches can be used together.

​
Choose a deployment method

In Forge, open Integrations → Forge Device Agent, select a platform, and choose direct download or managed deployment. Deployment material is created for your organization and should only be shared with administrators responsible for the rollout.

​
Enrollment token allowed uses

Direct setup commands include a bootstrap enrollment token. Allowed uses controls how many successful device enrollments can consume that token before Forge rejects it. The default is 1 for an individual install. Increase it only when you intentionally want to run the same generated command across a bounded set of clean hosts, such as a Linux VM batch, EC2 user data script, SSH loop, or Systems Manager command. Each successful new device enrollment counts as one use. Re-running the installer on a device that is already enrolled normally preserves that device identity and does not require another bootstrap token. If the token is expired, revoked, invalid, or has reached its allowed-use count, Forge rejects the enrollment and you should generate a new setup command. Use the smallest count that matches the rollout size, keep generated commands private, and avoid baking bootstrap tokens into long-lived images or shared scripts.

​
Windows setup

For a direct installation, download the Windows setup bundle from Forge and run it as an administrator on the target device. The device appears in Devices after it enrolls and sends its first signal. For Intune:
  1. Connect Microsoft Entra and confirm the requested Microsoft Graph access.
  2. Refresh the Microsoft connection so Forge can read the Entra users, Intune managed devices, and each managed device’s primary-user state.
  3. In Forge, generate the Windows deployment for your organization.
  4. Choose Guided upload to create the Win32 app using the settings Forge provides, or choose Automated to let Forge create it after your review.
  5. Assign the app as Required to a pilot Entra device group.
  6. Return to Forge and refresh the deployment to confirm the assignment and installed devices.
  7. Open Devices and review any unresolved or conflicting devices. They remain enrolled, collect telemetry, and apply device-scoped policy while awaiting an owner assignment. User-dependent native routing waits for an exact owner or service-account assignment; ordinary networking remains untouched.
Forge supplies the package, install and uninstall commands, requirements, and detection rule as one release. Keep those generated values together rather than mixing files or settings from different releases. Intune installs Forge in the device’s SYSTEM context. The endpoint user does not sign in to Forge, enter an enrollment code, or approve the installation. Consequently, No user on an Intune app-install status row means that the app was installed for the device rather than a user. It does not mean the Intune managed device lacks a primary user.

​
Associate Windows devices with people

Installation identity and user identity are deliberately separate:
  • Forge enrollment establishes the device and sensor installation identity.
  • The Device Agent reports the active OS login. Forge automatically assigns a person only when that login has exactly one match among active directory users in the organization. Ambiguous or missing matches remain unresolved.
  • An existing manual assignment or trusted MDM assignment always wins; a later login observation does not overwrite it.
  • Connecting Microsoft Intune, Jamf, or another MDM identity source is optional. It can improve matching and inventory readback, but is not required for enrollment, telemetry collection, or device-scoped policy. Without MDM, exact OS-login matching can establish the owner needed for native routing.
  • A managed service-account assignment can be used for a shared or non-human device instead of inventing a human owner.
For one-person corporate devices, keep directory usernames aligned with OS logins. Forge then resolves an exact unique match automatically. If Intune is connected and supplies a trusted primary-user assignment, Forge preserves that assignment instead. Administrators can always review or correct ownership in Devices. For shared devices, kiosks, build hosts, and servers, do not invent a human owner merely to clear the unresolved state. The agent continues to work. Leave the device unresolved until an administrator assigns the appropriate person, or assign an approved managed service account when the device should route as a non-human principal. Until then, user-dependent routing does not activate and ordinary network traffic remains untouched. Before expanding a rollout, filter Devices for unresolved and needs-review states. Resolve duplicate serial-number matches, conflicting MDM assignments, and ambiguous directory usernames. When a device changes hands, update its manual or MDM assignment. Forge does not replace an established assignment from a recent OS login.

​
macOS setup

The macOS download contains one signed unified installation package and the setup material needed for the selected deployment method. For a direct installation or update, download a fresh macOS package from Forge, extract the ZIP on the target Mac, and open the signed Install Forge.app. There is no separate Terminal command or unsigned updater. The app detects whether Forge is missing, already current, older, or newer; it refuses an accidental downgrade. Approve the administrator and macOS permission prompts when asked. The generated package enrolls one device in the organization for which it was created. Keep System Integrity Protection and Gatekeeper enabled. The customer setup uses signed release material and the normal macOS permission prompts. Disabling these protections in a test VM is not a customer installation step. Complete all installer checks before enabling device routing. The final check includes signed package receipts, saved enrollment, System Keychain trust, Network Extension readiness, notifications, Full Disk Access, sensor service health, and an accepted control-plane heartbeat. If the final heartbeat check fails, confirm that the Mac can reach the Forge service and that the service is healthy. Select Try Again to resume the saved setup. Keep the existing enrollment and do not repeatedly consume new bootstrap tokens to resolve a connectivity failure.

​
Deploy with an MDM

For Jamf, Iru, or another macOS MDM:
  1. In Forge, choose the MDM and download the generated macOS MDM handoff.
  2. Publish every included .mobileconfig as a device configuration profile and scope it to the pilot Macs before the application package.
  3. Upload the exact signed and notarized PKG. Do not rebuild, re-sign, or rename it or the profiles.
  4. Attach the included provider-neutral Before and Activate/Verify scripts. For Jamf, use the included Jamf aliases, policy template, and Extension Attribute. For Iru, use the included Custom App handoff manifest.
  5. Assign the profiles and app/package to a small pilot device group or Blueprint.
  6. Confirm package receipts, enrollment, authenticated heartbeat, System Extension activation, and MDM inventory/detection readback before expanding scope.
The handoff’s mdm-handoff.json binds the exact release, PKG hash, profile hashes, enrollment capacity and expiration, lifecycle scripts, and required install order. Jamf and Iru consume the same immutable signed release; provider selection does not create a different Forge binary. A Mac installed before anyone signs in can report Installed, Enrolled, and Pending activation. This is a successful pre-login deployment. The system service remains loaded and heartbeating, and Forge preserves the Mac’s existing network path. Network Extension activation completes after the first eligible console login without requiring a Forge login. Existing enrolled Macs preserve their device identity during an upgrade and do not require the bootstrap parameters again. Delete the downloaded bundle after deployment succeeds because its bootstrap token is sensitive.

​
Jamf Pro policy settings

For Jamf, recreate the included policy template:
  • Trigger: Login, so activation is verified while a user is signed in
  • Execution frequency: Once per computer
  • Scope: the same pilot group as the configuration profile
  • Package action: Install, with the Before script at priority Before and the After script at priority After
  • Maintenance: Update Inventory
For a new installation, set Before script parameter 4 to the contents of bootstrap-token.txt, parameter 5 to the Forge URL already shown in the policy template, and optionally parameter 6 to an owner email. For a controlled retry while a user remains signed in, add a custom trigger and run sudo jamf policy -event <custom-trigger> on the pilot Mac. When replacing an existing Forge profile, keep the same profile identifier and select Distribute to All in Jamf’s redistribution prompt. Newly Assigned Devices Only leaves the old permissions on Macs that already have the profile. To remove Forge, first remove the Mac from the configuration-profile scope and wait for Jamf to report the profile absent. Then run the included Uninstall script. If it reports reboot_required or user_action_required, follow that instruction and rerun it. The Jamf Pro integration is a separate, read-only connection for computer and owner inventory. It is not required to deploy Device Agent through Jamf.

​
Linux setup

The Linux Device Agent is intended for headless hosts, developer VMs, and server-style rollouts such as EC2 with Systems Manager. Install the generated Linux archive for the selected architecture, then run the sensor services under systemd. The installation script generated in Forge enables periodic connection discovery by default. Pass --linux-socket-inventory enabled or --linux-socket-inventory disabled to choose explicitly. Installing a downloaded .deb or .rpm directly, or using the MDM installer, leaves discovery off on a fresh install unless an administrator enables it. An upgrade preserves the existing service setting. After enrolling through a direct package install, enable discovery with this command. It updates and restarts the Forge services.
When enabled, the agent checks bounded connection and process metadata every five minutes. It identifies AI destinations when observed metadata matches the AI catalog; permissions and collection bounds can limit coverage. It does not inspect content, capture every connection between checks, or enable routing. Linux eBPF observation and route enforcement are separate capabilities. Check the selected device’s activity after a real connection to confirm detection. Linux endpoint route enforcement is local network enforcement. It can enforce bounded destination rules using destination domain or IP, protocol, destination port, and Linux process name when that process name is present. Domain rules are resolved to bounded IP rules on the device. For Flag for review access policies, Linux does not block the connection. It allows the traffic, records the matching route policy as workflow evidence, and uploads the event for review in Forge. For Block access policies, Linux uses local network enforcement when the rule is representable. Some Access policy fields depend on browser sessions, account attribution, model attribution, or other higher-level control point evidence. Linux devices do not broaden those rules into network-only blocks. Instead, Linux omits the route rule and records a route diagnostic. macOS and other supported endpoint routes keep their own behavior. Linux omits endpoint-route rules that use fields such as browser account state, browser extension identity, account posture or profile, source family or health, local model governance, local model proof, local model name, process ID, process entrypoint identity, classification state, or raw capture grants. To inspect what the Linux agent received, run:
ruleSummaries shows the route rules that Linux can enforce locally. routeDiagnostics explains any route rules that were omitted instead of broadened.

​
Turn on device routing

After devices enroll, open Devices, select the exact devices you want to manage, and enable Device routing. Forge checks device health and the routing path before showing the devices as Active. When a configured HTTP, HTTPS, PostgreSQL, MySQL, or Redis Resource has Automatic routing enabled, the same device routing setup sends connections to that Resource through Forge while users keep the original hostname, port, and client. Resource identity, credentials, policies, and activity are configured under Policies → Resources. See Resources. Direct and automatically routed connections use the same Resource policy, redaction, filtering, approval, credential, and Activity path. If approval is required, the first operation ends with a policy explanation and approval reference. After approval, the user retries the exact operation; the Device Agent does not hold the connection open. Once active, supported AI traffic is routed automatically. Users keep using their existing applications and provider interfaces; no application-by- application proxy configuration is required.

​
Restart existing browser connections

After enabling routing or adding an AI surface, wait for the updated routing configuration to be applied before testing. Browsers can reuse connections opened before the change, so requests on those connections may not be captured. Opening a new tab or window may still reuse the same connections. If browser activity does not appear in Forge, save any work, fully quit the browser, and reopen it. On macOS, use Quit or Command-Q; closing its windows alone may leave it running. If the browser does not exit, use Force Quit after saving your work. Then send a new test message to a selected AI surface and check for its session in Forge. Earlier requests are not captured retroactively.

​
Updates and removal

Deploy the complete release generated by Forge whenever you update Device Agent. On Windows, publish the new signed Intune app using supersedence or a new required assignment. For a directly installed Mac, return to Integrations → Forge for devices → macOS → Direct download, download the approved release, and open its signed Install Forge.app; the same guided app is the supported updater. For MDM-managed Macs, deploy the new unified package together with its matching profile and scripts. The macOS installer shows installation and update progress separately, refuses to install over a newer version, and does not show completion merely because the package command returned. It verifies that both installed receipts match the downloaded release and that enrollment, permissions, Network Extension, and launchd runtime readiness all pass. Forge preserves enrollment during a normal update and reports the version currently running on each device. To remove Device Agent, start the removal from Devices or your management workflow and wait for the device to restore its previous network settings. On Linux, run the packaged uninstall script with state removal enabled when you want to fully remove local Forge state, including routing artifacts:
On macOS, remove the MDM-owned configuration profile before uninstalling the package. Then run the packaged uninstall script:
Follow any macOS System Extension removal approval or reboot instruction. Sign back in after reboot so the product’s retained reconciliation service can finish cleanup. The Sensor scripts may already have been removed; their absence does not establish that System Extension cleanup is complete. If cleanup still needs attention and the retained product lifecycle exists, retry its supported operator command:
Wait for the Forge System Extension, application, and managed runtime to be removed before starting a new enrollment. The internal reconciliation mode is owned by the product service and is not an operator command. If cleanup remains pending, collect diagnostics or contact Forge Support instead of manually deleting files or editing reconciliation state.

​
Troubleshooting

For a final check, open the device in Devices and confirm its organization, version, recent heartbeat, and routing health. Then make a supported test request and verify that it appears under the appropriate LLM or MCP Gateway session.

​
Verify a pilot after installation or upgrade

Confirm the installed package version, fresh heartbeat, organization, and device identity. For an in-place upgrade, those identities should remain unchanged. Then check each feature you intend to deploy: inventory records, a supported hook callback, a bounded historical backfill, and routing allow/block/recovery. A successful installer or heartbeat alone does not prove all four. On macOS, verify the Network Extension and certificate trust required by the selected routing mode. Use the supported administrator approval or MDM profile; do not disable SIP or TLS verification. Restart browser connections after a routing change before testing a new request. Check server-side projection freshness separately from endpoint collection progress.