> For the complete documentation index, see [llms.txt](https://documentation.ocsinventory-ng.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ocsinventory-ng.org/developer-docs/setup-development-environment/agent.md). # Agent This guide walks a developer through setting up a local development environment for the [OCS Inventory Agent Rework](https://github.com/OCSInventory-NG/OCSInventory-Agent-Rework) repository - a complete rewrite of the OCS Inventory Agent in Dart, built for use with the 3.0 OCS Inventory server. This guide is for **development environments only**. For a production install of the agent, see the [OCS Inventory Agent Setup guide](/administrator-docs/agent-setup.md) instead, or grab a pre-compiled Windows binary from the [releases page](https://github.com/OCSInventory-NG/OCSInventory-Agent-Rework/releases). {% hint style="warning" %} This agent only works with OCS Inventory Server 3.0. It won't talk to a legacy 2.x server. {% endhint %} ### Overview This repository contains the agent only - the piece that runs on end-user machines and reports inventory data to the backend. To fully exercise it during development, you'll also need a running instance of the [backend API](https://github.com/OCSInventory-NG/OCSInventory-Server-Backend-Rework) for the agent to report to. The agent is a standalone Dart console application, with platform-specific packaging (`setup/linux`, `setup/windows`, `setup/macos`) to turn it into an installable service. ### Prerequisites * **The Dart SDK** - download the latest stable release for your platform from the [official Dart installation page](https://dart.dev/get-dart#install), then make sure the `dart` binary is available on your `PATH` by following the same page's instructions for your OS. * **Git** - to clone the repository. * Platform-specific build tools, only if you intend to compile the installable packages: * **Linux/macOS**: a standard shell environment is enough to run the provided `install.sh` / `uninstall.sh` scripts. * **Windows**: `Developer Command Prompt for VS 2022` (to run `build_all.bat`) and, optionally, [Inno Setup](https://jrsoftware.org/isinfo.php) if you want to build your own Windows installer package. * A running instance of the [backend API](https://github.com/OCSInventory-NG/OCSInventory-Server-Backend-Rework), since the agent has nothing to report to without one. ### Step 1 - Clone the Repository {% hint style="info" %} If you plan to contribute back to the project (bug fixes, features, pull requests), fork the repository on GitHub first and clone your fork instead of the main repository. This lets you push branches and open pull requests without needing write access to the original repo. {% endhint %} ```bash git clone https://github.com/OCSInventory-NG/OCSInventory-Agent-Rework.git cd OCSInventory-Agent-Rework ``` The default branch for active development is `main`. ### Step 2 - Install Dependencies From the project root, fetch the Dart packages the agent depends on: ```bash dart pub get ``` ### Step 3 - Run or Build the Agent For day-to-day development, you can run the agent's entry point directly with Dart, without compiling a binary each time: ```bash dart run lib/app/app.dart ``` When you need a standalone executable (e.g. to test the full install flow), compile it for your platform: ```bash dart compile exe lib/app/app.dart -o ocsinventory-cli ``` {% hint style="info" %} The compiled binary name and packaging steps differ slightly by OS - see the platform-specific compilation and installation instructions in the project's README (Linux, Windows, macOS) for the exact folder structure and scripts (`install.sh`, `build_all.bat`, the Inno Setup `.iss` script, etc.). {% endhint %} ### Step 4 - Configure the Agent for Local Testing Once installed (or when running the compiled binary directly), the agent reads its settings from a `config.json` file. Its location depends on your OS: | OS | Configuration directory | | ------------- | ------------------------------------ | | Linux / macOS | `/etc/ocsinventory-agent` | | Windows | `C:\ProgramData\OCSInventory-Agent\` | Key properties in `config.json`: | Property | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | URL of the backend server API you want the agent to report to. | | `username` / `password` | Credentials used to authenticate against the backend API in remote inventory mode. | | `mode` | Working mode: `1` remote with template, `2` remote without template, `3` local with template, `4` local without template. | | `data_directory` | Folder where the agent stores inventory data. | | `log_level` | `0` Critical, `1` Error, `2` Warning, `3` Info, `4` Debug. | | `log_file` / `log_file_path` | Whether to log to a file (instead of the terminal) and where. Note: the file itself isn't created automatically - you need to create it yourself. | | `certificate` | Path to a certificate file (`.pem`), required if the backend runs over HTTPS. | | `bypass-certificate` | Set to `true` to skip certificate validation - handy for a self-signed cert in a dev environment. | Example: ```json { "url": "http://localhost:8000", "username": "username", "password": "password", "mode": 2, "log_level": 4, "log_file": false, "data_directory": "/var/lib/ocsinventory-data", "certificate": null, "bypass-certificate": true } ``` {% hint style="warning" %} If your backend runs over HTTPS, you must supply a certificate - even a self-signed one - or set `bypass-certificate` to `true` (or pass `-b true` on Linux/macOS) to skip validation during local testing. {% endhint %} ### Uninstalling a Local Install If you installed the agent through the platform scripts while testing: | OS | How to uninstall | | ------- | ------------------------------------------------------------------------------------------------ | | Linux | Run `uninstall.sh` (with root privileges) from `/usr/share/ocsinventory-agent/setup/linux/`. | | Windows | Run the uninstaller from `C:\Program Files\OCSInventory-Agent\`. | | macOS | Run `uninstaller.sh` (with root privileges) from `/Applications/OCS-NG.app/Contents/Resources/`. | ### Troubleshooting | Symptom | Likely cause | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dart pub get` fails | Confirm the Dart SDK is installed and `dart` is on your `PATH` (`dart --version`). | | Agent can't reach the backend | Double-check `url` in `config.json` - including protocol (`http`/`https`) and port - and confirm the backend is running and reachable. | | Authentication errors | Verify `username` and `password` in `config.json`, and that the account has the needed permissions on the backend API. | | SSL/certificate errors | If the backend uses HTTPS, provide a valid `certificate` path, or set `bypass-certificate` to `true` for local/self-signed testing. | | No logs, or logs not where expected | Check `log_file` and `log_file_path` - remember the log file itself isn't created automatically; create it first. | | Nothing happens after restarting the service | Restart it explicitly: `sudo systemctl restart ocsinventory-service` (Linux), via Windows Services (Windows), or unload/reload the LaunchDaemon plist (macOS). | ### How to Contribute {% stepper %} {% step %} **Fork the repository** on GitHub, then clone your fork locally (see the note in Step 1 above). {% endstep %} {% step %} **Create a branch** for your change, based on `main`: ```bash git checkout main git pull git checkout -b my-feature-branch ``` {% endstep %} {% step %} **Make your changes**, following the existing code style. The repository includes several quality and security configs (`.cspell.json`, `.gitleaks.toml`, `.jscpd.json`, `.mega-linter.yml`) — running the relevant checks locally before committing will catch most issues early and matches what CI checks on your pull request. {% endstep %} {% step %} **Commit and push** your branch to your fork: ```bash git add . git commit -m "Describe your change" git push origin my-feature-branch ``` {% endstep %} {% step %} **Open a pull request** from your branch to the `main` branch of the main repository, with a clear description of what the change does and why. {% endstep %} {% endstepper %} {% hint style="info" %} Keep pull requests focused on a single change. Smaller, well-scoped PRs are easier to review and more likely to be merged quickly. {% endhint %} ### One Last Thing You just got a Dart agent talking to a backend it's never met before - that's not nothing. This little program is the one that actually walks onto thousands of real machines, quietly counts what's installed, and phones home so someone, somewhere, doesn't have to do it by hand with a spreadsheet. It runs on Linux, Windows, and macOS, often as a background service nobody thinks about - until it stops working, at which point everybody thinks about it. Every edge case you handle here saves a sysadmin from a bad day later. So compile that binary, point it at your local backend, and see what it reports. If something's off, that's not a dead end - that's your first pull request waiting to happen. 🚀 --- # 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://documentation.ocsinventory-ng.org/developer-docs/setup-development-environment/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.