> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/app-builder/build-backend/agents/native-agent.md).
# Native Agent
The Native Agent is a fully installable package. It registers itself as a background service (a Windows service or Linux daemon), so it runs around the clock without a logged-in user.
## How it works
* **Persistence**: The operating system manages the Agent (systemd on Linux, Service Manager on Windows). If the machine reboots, the Agent starts automatically.
* **Security**: The Agent connects through an outbound-only MQTTS connection on port 8883. No inbound firewall rules or VPNs are required.
* **Compatibility**: Available for Windows, macOS, Linux (standard and Alpine), and ARM64 (for industrial PCs).
## Installing the Native Agent
{% stepper %}
{% step %}
#### Configure and build
In the [Function Explorer](/app-builder/build-backend/functions/function-explorer.md), click the create Agent icon (:cloud-arrow-down:).
* **Connectors**: Select the connectors (e.g., S7, SQL) this Agent should carry.
* **Target OS**: Choose the operating system of the machine where the Agent will run.
* **Prefix (optional)**: Enter a [prefix](#using-a-prefix-for-fleet-deployment) if you plan to deploy the same file to multiple machines (e.g., `milling-machine-`). Each instance then generates its own unique ID (e.g., `milling-machine-abc123`).
* Click Prepare for Download to compile and download your installer package.
{% hint style="info" %}
#### Lost your file?
All Agents you have built are backed up on the [file server](/app-builder/build-backend/file-explorer.md) in the `native-agents` folder.
{% endhint %}
{% endstep %}
{% step %}
#### Run the installer
Move the package to the target machine, unzip, and run the installer.
* **Windows**: Run the `.exe` installer. It registers the service and starts the Agent automatically.
* **Linux/macOS**: Run the provided install script. You likely need `sudo` privileges so the Agent can register as a system daemon.
{% endstep %}
{% step %}
#### Automatic discovery
The service starts immediately after installation. The Agent and its connectors appear in the [Function Explorer](/app-builder/build-backend/functions/function-explorer.md). Drag these functions onto the Backend Builder canvas. In production Apps, they execute locally on the machine running the Agent.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
#### Troubleshooting: check port 8883
The Agent requires port 8883 to be open for outbound traffic. If the Agent runs but does not appear in your Function Explorer, ask your IT administrator to check whether a firewall blocks this port.
{% endhint %}
## Managing the Agent service
The Agent runs as a service and has no user interface window. Manage its state with the standard OS tools:
* **Windows**: Open the Services app (`services.msc`), find the Heisenware Agent, and use the Start, Stop, or Restart controls.
* **Linux**: Manage the daemon on the command line:
* `sudo systemctl status heisenware-agent`
* `sudo systemctl restart heisenware-agent`
## Using a prefix for fleet deployment
The prefix option changes how an Agent identifies itself. Use it to manage a fleet of similar machines or devices.
* **Without a prefix (default)**: The Agent has a built-in, unique ID. You can move the installer to different computers, but they are all recognized as the same single Agent.
* **With a prefix**: The Agent generates a new, unique ID on its first launch in a specific directory. Deploy the exact same installer on multiple machines and each one connects as a separate entry in your Function Explorer (e.g., `milling-machine-abc123`, `milling-machine-xyz789`).
{% hint style="danger" %}
Do not move an Agent folder that was created with a prefix after it has run for the first time. It relies on a hidden ID file in its directory to maintain its unique identity.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.heisenware.com/app-builder/build-backend/agents/native-agent.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.