> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/on-premise-active-directory-agent/running-the-agent.md).

# Running the agent

### Running the Agent <a href="#running-the-agent" id="running-the-agent"></a>

Before starting the service, ensure configuration is complete:

1. **Configure using TUI** (recommended):

   ```powershell
   & "C:\Program Files\BalkanID\ad-agent\BalkanID AD Agent.exe" --configure
   ```

   Complete all configuration steps, then exit the TUI.
2. **Or manually edit** `C:\ProgramData\BalkanID\ad-agent\config.yaml`

The agent can be run in two different ways:

#### I. Using the TUI (Terminal User Interface) <a href="#using-tui-terminal-user-interface" id="using-tui-terminal-user-interface"></a>

The TUI provides an interactive interface for monitoring and configuration:

1. **Launch TUI Mode**:\
   Run the following command in the terminal.

   ```powershell
   & "C:\Program Files\BalkanID\ad-agent\BalkanID AD Agent.exe" --tui
   ```
2. **TUI Features**:
   * **Dashboard**: View service status, connection status, and logs
   * **Configuration Menu**: Edit settings, test connections, regenerate API keys
   * **Real-time Logs**: Monitor agent activity
   * **Keyboard Shortcuts**:
     * `C` - Open Configuration Menu
     * `R` - Restart Server
     * `Q` - Quit
     * `U` - Check for Updates
3. **Exiting TUI**:
   * Press `Q` to quit
   * The server will stop when you exit the TUI

***

#### II. Running as Windows Service (Headless) <a href="#running-as-windows-service-headless" id="running-as-windows-service-headless"></a>

For production deployments, run the agent as a Windows service that operates in the background without a UI.&#x20;

**Service Behavior**

When running as a service:

* The agent runs in **headless mode** (no UI)
* It automatically starts on system boot
* Logs are written to `C:\ProgramData\BalkanID\ad-agent\logs\`
* If **Heartbeat Mode** is enabled, it will:
  * Extract AD data every 2 hours
  * Process requests every 10 minutes
  * Upload data to BalkanID automatically

**Step 1: Start the Service**

The service should already be installed by `install.ps1`. Start it:

```powershell
Start-Service -Name "BalkanIDADAgent"
```

**Step 2: Verify Service Status**

Check that the service is running:

```powershell
Get-Service -Name "BalkanIDADAgent"
```

The status should show `Running`.

**Step 3: Monitor Logs**

View the service logs:

```powershell
# View recent logs
Get-Content "C:\ProgramData\BalkanID\ad-agent\logs\*.log" -Tail 50

# View Windows Event Log
Get-EventLog -LogName Application -Source "BalkanIDADAgent" -Newest 10
```


---

# 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.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/on-premise-active-directory-agent/running-the-agent.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.