Settings

Agent configuration is done from the Agent interface itself, not by editing files by hand. This page documents what options there are, where they are stored internally, and how to retrieve them if you need to clone or migrate settings.

Set up connection to Zoan Cloud

It is the only thing that needs to be configured for the Agent to work. This is done on the “Connect this computer” screen the first time you open the Agent:

• Zoan Cloud URL — the URL of your tenant portal (e.g. https://acme.cloud.zoansoftware.com).
• Machine Key — the key generated when creating the agent from the portal.

See Windows Installation → Connect the Agent to Zoan Cloud for the detailed procedure.

Running as administrator is required

The configuration screen (both initial registration and any subsequent changes) only works if the Agent is opened as administrator. This prevents an unprivileged user from changing the connection on a shared machine.

If you open the Agent as a normal user, the fields appear read-only and the save button is disabled, with a warning to reopen it as admin.

Reconfigure after the first time

After the first registration, you can:

• Disconnect and Reconnect — from the footer of the main screen there is a Disconnect button that clears the settings and returns to the home screen.
• Change Instance — if you want to move the Agent to a different Zoan Cloud (e.g. from “Test” to “Production”), disconnect it and reconnect it with the new URL and Machine Key.
• Regenerate the Machine Key — if you lose it or suspect compromise, you regenerate the agent’s key from the portal. The previous key is immediately invalidated. Then you update the Agent with the new key.

Where are settings saved?

The Agent persists the configuration in:

C:\ProgramData\Zoan\Agent\agente.json

It is a JSON file with this structure:

{
  "nexusUrl":      "https://acme.cloud.zoansoftware.com",
  "machineKey":    "85f33cc1-f019-f0c1-50f1-97...",
  "agentId":       "a1b2c3d4-5678-90ef-...",
  "environmentId": "e1f2g3h4-...",
  "logLevel":      "info"
}

Do not edit the file by hand

• The file is rewritten every time you change something from the UI — your manual edits are lost.
• If the JSON format becomes invalid, the Agent discards it and returns to the “Connect this computer” screen.
• The Machine Key is in plain text. If you need to clone it to another machine, treat the file as a secret: restrictive permissions and secure deletion when you no longer use it.

Nivel de log

By default the Agent writes logs with level info. There are four levels available:

Nivel	What records
debug	Maximum detail: every bridge call, every heartbeat, every internal step. Useful for diagnosis — produces a lot of volume.
info	Significant events: registration, executions started and finished, errors. Recommended in production.
warn	Just warnings and errors.
error	Just mistakes.

To change the level, edit agente.json (with the Agent closed) and modify "logLevel", or use the Advanced Settings option from the system tray menu (coming soon).

Archivos relacionados

Other directories and files that the Agent uses:

C:\ProgramData\Zoan\
├── Agent\
│   ├── agente.json              ← configuración (la que ves arriba)
│   └── logs\
│       ├── service.log          ← logs del servicio Windows (modo desatendido)
│       └── ui.log               ← logs de la UI (modo atendido)
├── Packages\                    ← paquetes de actividades instalados (.zpkg)
│   ├── Zoan.Packages.Browser.1.0.0\
│   ├── Zoan.Packages.Excel.1.0.0\
│   └── ...
└── Automations\                 ← proyectos descargados de Zoan Cloud para ejecutar (.zoan)
    └── <execution-id>\

Environment variables (optional)

For special cases (CI/CD environments, containers, provisioning scripts), the Agent can read configuration from environment variables instead of agente.json:

Variable	Equivalente JSON
ZOAN_NEXUS_URL	nexusUrl
ZOAN_MACHINE_KEY	machineKey
ZOAN_LOG_LEVEL	logLevel

If the variables are set when the Agent starts, they have priority over the file. Useful for automating the provisioning of many agents with a configuration tool (Ansible, Group Policy, etc.).