> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnilinker.pl/llms.txt > Use this file to discover all available pages before exploring further. # Agent configuration reference > Every setting in the ERP Sync agent's appsettings.json, where the agent reads its configuration from, and where it keeps its local files. Most of the ERP Sync agent's behavior is set in Omnilinker, on the connection's sync configuration, and the agent downloads it. See [Sync configuration](/erp/sync-configuration). The local settings on this page are for the machine the agent runs on. You rarely need to change them. ## Where the agent gets its configuration | Source | What it holds | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `credentials.dat` | The API key, API URL, connection, organization ID, ERP database settings and company ID. Written by the [setup wizard](/erp/setup-wizard) and the tray app's **Settings...**. This is the only place the agent reads the API key, connection and database settings from. | | Omnilinker (cloud) | The connection's sync configuration: what to sync, intervals, batch sizes, field mappings. The agent fetches it every 5 minutes and keeps a copy in `config-cache.json` for when Omnilinker cannot be reached. | | `appsettings.json`, `ErpSync` and `Updates` sections | Local, machine-level settings, described below. | | Environment variables | Override `appsettings.json` values. | For the settings in `appsettings.json`, the order of precedence is, highest first: 1. Command-line arguments. 2. Environment variables, named `
__`, for example `ErpSync__PollingIntervalSeconds` or `Updates__Channel`. 3. `appsettings.json` in the install folder. 4. The built-in defaults listed below. Where a setting also exists in the cloud configuration or in `credentials.dat`, that value wins. Each setting below says so. `ApiKey` and `ConnectionId` in `appsettings.json` and in environment variables are ignored. The agent takes the API key and connection only from `credentials.dat`. Configure them with the [setup wizard](/erp/setup-wizard). ### Change a setting Set the value as a machine environment variable, in PowerShell as Administrator, then restart the service. The service reads these settings only when it starts: ```powershell theme={null} [Environment]::SetEnvironmentVariable("ErpSync__PollingIntervalSeconds", "120", "Machine") Restart-Service OmnilinkerErpSyncService ``` You can also edit `appsettings.json` in the install folder, by default `C:\Program Files\Omnilinker\ErpSync\current`, as an administrator, and restart the service. Every update replaces `appsettings.json`, and the agent [updates itself](/erp/install-agent#update-the-agent) at night. A change you made in the file is then lost without notice. Environment variables are not affected by updates, so prefer them. The shipped file looks like this (its `Logging` section is left out): ```json appsettings.json theme={null} { "ErpSync": { "ApiUrl": "https://omnilinker.pl", "LocalApiPort": 5555, "PollingIntervalSeconds": 60, "OutboxBatchSize": 100, "OutboxPublishIntervalSeconds": 5, "MaxRetryAttempts": 5, "AutoUpdateEnabled": true, "ConnectionId": null, "ApiKey": null, "PluginsPath": "plugins" }, "Updates": { "FeedUrl": "https://releases.omnilinker.com/erpsync", "Channel": "stable" } } ``` ## Settings "Default" is the value the agent uses when the setting is missing from `appsettings.json`. ### Cloud connection | Setting | Type | Default | Meaning | | -------------- | ------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ApiUrl` | string | `https://omnilinker.pl` | Omnilinker's address. The API URL saved by the setup wizard in `credentials.dat` takes precedence, so this value is used only before the wizard has run. Change the URL in **Settings...** instead. | | `ApiKey` | string | `null` | Ignored. See the note above. | | `ConnectionId` | GUID | `null` | Ignored. See the note above. | ### Local API | Setting | Type | Default | Meaning | | -------------- | ------- | ------- | ------------------------------------------------------------------------------------ | | `LocalApiPort` | integer | `5555` | The port of the agent's [local API](/erp/local-api). It listens on `localhost` only. | Leave `LocalApiPort` at `5555`. Omnilinker's web app and the tray app's fallback connection both expect the local API on port 5555 and do not read this setting. ### Change detection | Setting | Type | Default | Meaning | | ------------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `PollingIntervalSeconds` | integer | `60` | How often the polling cycle runs, in seconds. In hash scan mode this is how quickly a **Sync Now** request is picked up. | | `HashCheckIntervalSeconds` | integer | `900` | Seconds between hash checks, used only until the cloud configuration has loaded. After that, the connection's hash check interval applies. | | `HashCheckInitialDelaySeconds` | integer | `120` | Seconds to wait after the service starts before the first hash check. | | `HashCheckFetchBatchSize` | integer | `100` | How many changed records a hash check reads from the ERP at a time. | ### Sending to Omnilinker The agent queues every change in a local outbox and sends it to Omnilinker in batches. | Setting | Type | Default | Meaning | | ------------------------------ | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `OutboxBatchSize` | integer | `500` | Maximum events per batch. The shipped `appsettings.json` sets `100`. The connection's sync configuration takes precedence when it sets a batch size. | | `CloudApiBatchHardLimit` | integer | `1000` | Upper limit for events per request, whatever the other settings say. Omnilinker accepts at most 1,000 events per request, so do not raise it. | | `OutboxDrainThreshold` | integer | `1000` | When more events than this are waiting, the agent sends batches back to back, without the pause between them, until the backlog is cleared. | | `OutboxPublishIntervalSeconds` | integer | `5` | Seconds between send cycles, used only until the cloud configuration has loaded. After that, the connection's value applies. | | `MaxRetryAttempts` | integer | `5` | How many times the agent tries to send an event before marking it as failed. | ### Plugins | Setting | Type | Default | Meaning | | ------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------ | | `PluginsPath` | string | `plugins` | Reserved. It has no effect yet: the agent does not load providers from a plugins folder. The Wapro provider is built in. | ### Updates How the agent [updates itself](/erp/install-agent#update-the-agent). `AutoUpdateEnabled` is in the `ErpSync` section. The others are in the `Updates` section, so their environment variables start with `Updates__`. | Setting | Type | Default | Meaning | | ------------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `AutoUpdateEnabled` | boolean | `true` | `false` turns automatic updates off. You then update by hand. | | `FeedUrl` | string | none | Where the agent looks for new versions. The shipped file sets `https://releases.omnilinker.com/erpsync`. Empty turns updates off. Do not change it. | | `Channel` | string | none | Which releases the agent takes. The shipped file sets `stable`. | | `CheckEvery` | time span | `04:00:00` | How often the agent looks for a new version. | | `FirstCheckAfter` | time span | `00:05:00` | How long after the service starts it looks for the first time. | | `ApplyFrom` | time of day | `01:00` | Start of the nightly window in which a downloaded version is installed, in the computer's local time. | | `ApplyUntil` | time of day | `05:00` | End of that window. The window can run past midnight, for example `22:00` to `04:00`. | A version is installed only inside the window and only when no sync is running. If installing fails, the agent tries again the next night. ### Fixed values The agent has these settings internally, but does not read them from `appsettings.json` or environment variables. They always have the values shown. They are listed so you can interpret the agent's logs. | Setting | Value | Meaning | | -------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `OutboxPublisherStartupDelaySeconds` | `10` | Seconds after start-up before the first send cycle. | | `PhaseAdvanceFailedGraceMinutes` | `30` | With WFM\_INT change tracking, how long a sync phase waits on events that failed all retries before moving on with a warning. | | `ChangeConsumptionIntervalSeconds` | `60` | With WFM\_INT change tracking, seconds between cycles that read changes from the ERP. | | `ChangeConsumptionStartupDelaySeconds` | `5` | Seconds after start-up before the first WFM\_INT cycle. | | `ChangeConsumptionCycleBudgetSeconds` | `45` | Time limit per change stream per WFM\_INT cycle, so one busy stream cannot hold up the others. | | `HeartbeatIntervalSeconds` | `60` | Seconds between heartbeats to Omnilinker. | | `CapabilitiesRefreshIntervalSeconds` | `600` | How often the agent checks again what the ERP supports, in seconds. | | `ReferenceSyncIntervalSeconds` | `86400` | How often the ERP's reference (dictionary) data is uploaded again: daily. | | `ReferenceChunkSize` | `500` | Reference items per upload. | | `BundleCompositionSyncIntervalSeconds` | `21600` | How often bundle compositions are read in full: every 6 hours. | | `ReconciliationIntervalSeconds` | `604800` | With WFM\_INT change tracking, how often a full reconciliation check runs: every 7 days. | ## Logging The service writes one log file per day to `%ProgramData%\Omnilinker\ErpSync\logs` (see [Local files](#local-files)) and keeps the last 30 files. Each line has a timestamp, the level, the component and the message. Setup, updates and uninstalling add to `setup.log` in the same folder: `done`, or one line for each step they could not complete. The log level is fixed: `Information` for the agent, `Warning` for framework components. The `Logging` section in `appsettings.json` has no effect on the log files. ## Local files The agent keeps three folders on the machine. **Install folder**: `C:\Program Files\Omnilinker\ErpSync\current` when you install as described in [Install the agent](/erp/install-agent). Setup replaces its contents on every update. | File | Contents | | ---------------------------------------------- | ------------------------------------------------------------------------------------------- | | `Omnilinker.ErpSync.Service.exe` | The Windows service. | | `tray\Omnilinker.ErpSync.Tray.exe` | The tray app, in a subfolder of its own. | | `appsettings.json` | The settings on this page. Replaced on every update. | | `install-service.ps1`, `uninstall-service.ps1` | Only for a [portable copy](/erp/install-agent#portable-copy-zip). Setup does not need them. | **Data folder**: `%ProgramData%\Omnilinker\ErpSync`, usually `C:\ProgramData\Omnilinker\ErpSync`. The service and everyone who uses the tray app see the same folder. Setup lets only SYSTEM and administrators change it. Other users can read it. | File | Contents | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `credentials.dat` | API key, API URL, connection, organization ID, ERP database settings and company ID. Encrypted with Windows DPAPI, machine scope: it can be decrypted only on this computer. Only SYSTEM and administrators can open the file. | | `logs\erpsync-.log` | Service log files, one per day, 30 kept. For example `erpsync-20260927.log`. | | `logs\setup.log` | What setup, updates and uninstalling could not do. | **Service profile folder**: `C:\Windows\System32\config\systemprofile\AppData\Local\Omnilinker\ErpSync`, the local application data folder of Local System, which the service runs as. | File | Contents | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `erpsync.db` | Local SQLite database: the outbox of events waiting to be sent, the local sync log, and the agent's change-detection state. `erpsync.db-wal` and `erpsync.db-shm` next to it belong to it. | | `config-cache.json` | The last cloud configuration the agent received, used when Omnilinker cannot be reached at start-up. | Do not delete `erpsync.db` while the agent is installed. Events that have not been sent yet are lost, and the agent has to rebuild its change-detection state.