> 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/administrator-docs/agent-setup/configuration.md).

# Configuration

Configure how the agent runs, connects to the server, and handles deployment.

The agent uses a local configuration file in both local and remote modes.

{% hint style="warning" %}
Configuration files use JSON syntax. In `config.json`, always write Windows paths with forward slashes (e.g., `C:/ProgramData/OCSInventory-Agent`) rather than backslashes. This applies to both the interactive installer and silent installs.
{% endhint %}

### Configuration details

Below is an example of the `config.json` content and a table explaining each option:

```json
{
  "url": "https://server_ip:port",
  "username": "username",
  "password": "password",
  "mode": 1,
  "data_directory": "/var/lib/ocsinventory-data",
  "log_level": 3,
  "log_file": true,
  "log_file_path": "/var/log/ocsinventory-agent/ocsinventory-agent.log",
  "certificate": "/path/to/cert.pem",
  "bypass_certificate": false
}
```

<table><thead><tr><th width="184">Field</th><th width="94">Type</th><th width="116">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>url</code></td><td>string</td><td>Online modes only</td><td>OCS server API base URL. Example: <code>http(s)://server_ip:port</code>.</td></tr><tr><td><code>username</code></td><td>string</td><td>Online modes only</td><td>API username used for authentication.</td></tr><tr><td><code>password</code></td><td>string</td><td>Online modes only</td><td>API password used for authentication.</td></tr><tr><td><code>mode</code></td><td>int</td><td>Yes</td><td>Execution mode (see list below).</td></tr><tr><td><code>data_directory</code></td><td>string</td><td>Yes</td><td>Base directory for inventory files and deployment cache. Inventory JSON is written to this path.</td></tr><tr><td><code>log_level</code></td><td>int</td><td>No</td><td>Log verbosity: <code>0</code> Critical, <code>1</code> Error, <code>2</code> Warning, <code>3</code> Info, <code>4</code> Debug.</td></tr><tr><td><code>log_file</code></td><td>bool</td><td>No</td><td>Write logs to a file (<code>true</code>) or only to stdout (<code>false</code>).</td></tr><tr><td><code>log_file_path</code></td><td>string</td><td>No</td><td>Full path to the log file. Used only when <code>log_file</code> is <code>true</code>.</td></tr><tr><td><code>certificate</code></td><td>string</td><td>No</td><td>Path to a PEM certificate file.</td></tr><tr><td><code>bypass_certificate</code></td><td>bool</td><td>No</td><td>If <code>true</code>, TLS certificate validation is disabled.</td></tr></tbody></table>

{% hint style="warning" %}
The user account specified in the agent configuration is used to authenticate with the backend server. It must therefore have the following permissions:

* General Configuration: View
* Inventory - Logs: Add
* Inventory - Assets: View
* Templates: View
* Deployment - Actions: View
* Deployment - Results: View, Edit

See [Groups and permissions](/administrator-docs/server-setup/configuration/basics/groups-and-permissions.md) for more details.
{% endhint %}

### Execution modes

Execution mode controls two things: where inventory goes (server (**remote**) vs disk (**local**)) and whether **templates** are used.

**Mode values**

* 1 → Remote with template
* 2 → Remote without template
* 3 → Local with template
* 4 → Local without template

{% hint style="info" %}
**Remote modes (1/2)** require server access.

**Local modes (3/4)** are for offline workflows.
{% endhint %}

### TLS / SSL configuration

* HTTPS with a cert trusted by the OS: no extra config needed. Leave `bypass_certificate: false`.
* HTTPS with a self‑signed or private CA:
  * Preferred: install the CA in the OS trust store and keep `bypass_certificate: false`.
  * Fallback: set `bypass_certificate: true` (accepts any cert; use only if you understand the risk).

{% hint style="warning" %}
Setting `bypass_certificate: true` disables certificate validation.
{% 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://documentation.ocsinventory-ng.org/administrator-docs/agent-setup/configuration.md?ask=<question>&goal=<endgoal>
```

`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.