Agent FAQ

Common questions about the Vile Analyziz endpoint agent. For error codes, see the Error Code Reference in the portal.

How do I install the agent on Windows?

Download the installer (MSI or EXE) from the portal Agents page. Run it as Administrator. The installer places the agent in Program Files, installs the Windows service, and optionally prompts for an enrollment code. For silent deployment: msiexec /i va-agent.msi /qn ENROLLMENT_CODE=XXXXX

The agent shows "Not enrolled" after installation. What do I do?

Go to the portal Agents page and create an enrollment code. Enter it in the agent dashboard when prompted, or run: va enroll --code YOUR_CODE from a terminal.

I double-clicked va-gui.exe but nothing happened.

Check the log file at %APPDATA%\va\logs\va-gui.log for errors. Common causes: missing .NET runtime (not needed, but SmartScreen may block unsigned binaries), antivirus blocking the executable, or a stale config file from a previous installation. Run va reset --confirm to clear old data.

The dashboard says "Device deactivated." How do I fix it?

Your administrator deactivated this device in the portal. Contact them to reactivate it, or click "Re-enroll with new code" in the recovery screen to create a new device record.

I see 500 errors in the agent logs. Is something broken?

A 500 error from the server is usually a transient issue (database timeout, service restart). The agent retries automatically. If 500 errors persist for more than 10 minutes, check the portal status page or contact support. Error code VA-TOKEN-003 indicates the server is temporarily busy.

How do I update the agent?

Run va update from a terminal to check for and apply updates. The dashboard also shows a banner when a new version is available. For fleet updates, deploy the new installer via your management tool (GPO, Intune, etc.).

Can I run the agent without installing it as a service?

Yes. Double-click va-gui.exe to run in foreground mode with a local dashboard. The agent stops when you close it or log out. For persistent protection across reboots, install as a service: va service install && va service start.

How do I completely remove the agent?

Use Add/Remove Programs (if installed via MSI/EXE), or run: va service stop && va service uninstall to remove the service, then delete the binary. To clear all data including enrollment: va reset --confirm.

What does the agent scan? Can I control which directories?

The agent scans directories specified in the scan policy (configured by your administrator in the portal). Default: user home directory. Policies control which file types, size limits, and exclude paths apply. System directories (Windows, Program Files, /proc, /sys) are always excluded.

Is the agent using too much CPU or memory?

The agent limits itself to half your CPU cores and 256 MB memory. During initial scans, CPU usage may be higher as it processes files for the first time. Subsequent scans are incremental (only new/modified files). If resource usage seems high, check the policy interval and scan root configuration.

What happens when a file is quarantined?

The agent moves the file to a protected quarantine directory (~/.va/quarantine/) with read-only permissions. The file is not deleted. You can restore it from the dashboard or request IT approval. The quarantine event is logged to the portal audit trail.

Can I use the agent behind a corporate proxy?

Yes. The agent respects standard HTTP_PROXY and HTTPS_PROXY environment variables. Set them before starting the agent or configure them system-wide.

Where are the agent log files?

Windows GUI: %APPDATA%\va\logs\va-gui.log. Windows Service: check Windows Event Viewer under Applications. Linux: journalctl -u va-agent. Logs are JSON-formatted, rotated at 10 MB with 3 backups.

How do I enroll multiple devices at once?

Create an enrollment code with a high max_uses (up to 10,000) and a longer TTL (7-30 days). Use the same code across all devices. The portal tracks usage per code. For silent deployment: include ENROLLMENT_CODE in your MSI properties or deployment script.

The agent keeps retrying and failing. How do I reset it?

Run va reset --confirm from a terminal (as Administrator on Windows). This clears all agent data including enrollment, cache, and quarantine. Then re-enroll with a fresh code.

Still need help?

Contact your IT administrator or submit a support request.