> For the complete documentation index, see [llms.txt](https://docs.xygeni.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xygeni.io/xygeni-products/xygeni-shield/agent-settings.md).

# Agent settings

Besides the protection policy, a few settings control how the Shield agent itself works on each machine. They are always local to the machine, also on centrally managed machines, and the defaults suit most cases.

### On-premises Xygeni

By default Shield connects to Xygeni Cloud (`https://api.xygeni.io/api/v1/firewall`) and to the hosted malicious packages database (`https://apipmd.xygeni.io/api/v1`). For an on-premises Xygeni installation, point Shield at your servers:

```bash
sudo xygeni-fw config server-url https://xygeni.example.internal/api/v1/firewall
sudo xygeni-fw config malware-url https://malware.example.internal/api/v1
xygeni-fw config show        # the URLs in use, and whether a token is set
```

Shield picks up the change without a restart. An empty value (`""`) restores the default.

### The configuration file

The settings are in `firewall.yaml`:

* Linux: `/etc/xygeni-fw/firewall.yaml`
* Windows: `C:\ProgramData\Xygeni\Shield\config\firewall.yaml`

Restart the service after editing it (`sudo systemctl restart xygeni-fw` on Linux, `Restart-Service XygeniShield` on Windows).

```yaml
monitored_domains:                 # registries whose downloads are inspected
  - registry.npmjs.org
  - pypi.org
  - files.pythonhosted.org
  # ... (the full list of public registries, see System requirements)

malware_db:
  enabled: true                    # use the Xygeni malicious packages database
  sync_interval_minutes: 360       # how often to check for updates

fs:
  enforce: true                    # file protection on/off
  watch_paths:                     # extra places to watch (see below)
    - /tmp
    - /var/tmp
    - /media
    - /mnt
    - /run/media

alert_throttle_secs: 0             # 0 = one alert per block

log_level: info                    # error | warn | info | debug
```

| Setting                            | What it does                                                                                                                                                                                         |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `monitored_domains`                | The hosts whose downloads Shield inspects. Add your own registry mirrors here so their downloads are checked too. Traffic to any other host is not inspected.                                        |
| `malware_db.enabled`               | Turns the Xygeni malicious packages database on or off. Only turn it off if the machine cannot reach it; the rest of the policy keeps working.                                                       |
| `malware_db.sync_interval_minutes` | How often Shield checks for updates of the database (every 6 hours by default, and at start-up when the last check is older than that).                                                              |
| `fs.enforce`                       | Turns [file protection](https://docs.xygeni.io/xygeni-products/xygeni-shield/files-and-scans.md) on (default) or off. Download inspection keeps working when it is off.                              |
| `fs.watch_paths`                   | **Linux**: the places file protection watches. **Windows**: extra folders to watch on top of the built-in ones (Downloads, Temp and package caches).                                                 |
| `alert_throttle_secs`              | When the same package, host or IP is blocked again and again, report it only once every this many seconds. Blocking is never affected, only the number of alerts. `0` (default) reports every block. |
| `log_level`                        | How much detail the agent writes to its log.                                                                                                                                                         |

{% hint style="warning" %}
On Linux, file protection watches whole **mounted file systems**, not single folders. If a path in `fs.watch_paths` is not a mount point of its own (on many machines `/tmp` is just a folder of `/`), Shield watches the whole file system that contains it. The log says so at start-up (`fs watcher scope is WIDER than configured`).
{% endhint %}

### Who can manage Shield on a machine

* Reading the state (`xygeni-fw status`, alerts, the tray app) is available to the users of the machine: on Linux, the members of the `xygeni-fw` group, to which the installer adds the desktop user.
* Sensitive actions are only accepted from an administrator (root on Linux, an elevated administrator on Windows) or from the user who activated Shield on the machine: changing the token, saving the local policy from the tray app, releasing or deleting quarantined files, and releasing an isolation with a manual code.
* From the command line, changing the local policy or the agent settings is done with administrator rights (`sudo` on Linux, an elevated terminal on Windows).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xygeni.io/xygeni-products/xygeni-shield/agent-settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
