Architecture

Zoan Automation is made up of three components that work together. Understanding how they communicate helps you install, secure and diagnose the platform.

flowchart TB
  subgraph nube["NEXUS · nube — tu-empresa.cloud.zoansoftware.com"]
    portal["Portal web · API REST · Gateway WebSocket de agentes"]
  end
  designer["DESIGNER · tu PC<br/>diseña y prueba"]
  agent["AGENT · PC o servidor<br/>ejecuta los bots"]
  designer -->|"publica paquetes (HTTPS)"| nube
  agent -->|"WebSocket saliente (wss/443)<br/>heartbeat · órdenes · logs"| nube

Components

Zoan Cloud

The central backend and the brain of the platform. It lives in the cloud, under your organization’s subdomain. It is responsible for:

• Manage tenants, environments, agents, processes, executions, triggers and credentials.
• Expose a REST API for administration and integration.
• Serve the web portal where you manage and monitor everything.
• Maintain a WebSocket gateway to which agents connect to receive orders and report status.

Agent

Windows application that is installed on the machine where the automations will run. It connects to Zoan Cloud with a Machine Key and waits for orders. It can work in two modes:

• Attended: within an open Windows user session (the person launches the bot on their computer).
• Unattended: As a Windows service in the background, on a server with no one present. To automate the interface (desktop or windowed browser) in this mode, the agent uses a robot session—a Windows account—to open a desktop where the bot can work.

See What is an agent, Robot sessions and Installation on Windows.

Designer

The visual editor of automations (desktop app). You build playbooks by dragging activities, configuring parameters and defining variables; you test locally; and then you publish them to Zoan Cloud, where they are assigned to processes. See Designer Overview.

A single installer

Designer and Agent are distributed together in the Zoan Platform installer. The same machine can have both (you design and execute there) or only one (an unattended server normally has only the Agent).

How they communicate

The key piece is the Agent → Zoan Cloud connection:

• The Agent always initiates the connection to Zoan Cloud through a secure WebSocket (wss://, on port 443). Zoan Cloud never opens connections to the agent.
• On that channel, the Agent sends a periodic heartbeat (“I’m still alive and available” signal). If Zoan Cloud stops receiving it, it marks the agent as offline.
• Through the same channel, Zoan Cloud dispatches execution and cancellation orders, and the Agent returns logs and results in real time.

Implication for corporate networks

Since the Agent only makes outbound connections to port 443, you do not need to open inbound ports or publish the machine to the Internet. Simply allow outgoing HTTPS/WSS traffic to your Zoan Cloud subdomain. If there is a corporate proxy, it must allow WebSockets.

Flow of an execution

1. When launching the execution (manual or by trigger), the process, the agent and the robot session with which it will run are chosen.
2. Zoan Cloud sends the order to the selected agent via the WebSocket (it does not distribute it or choose the agent for you).
3. The agent downloads the package in the process version and executes it locally with the Runner.
4. During the run, logs and status flow back to Zoan Cloud in real time.
5. Upon completion, the result (completed / failed) is recorded in the execution history.

Ver Estados y ciclo de vida.

Deployment topologies

There is no single correct way; It depends on whether you automate attended tasks or unattended processes:

Escenario	Where does the Agent go?	Mode
Personal assistant for a user	That person’s PC	Attended (user session)
High volume night process	A dedicated server or VM	Desatendido (servicio de Windows)
Varias automatizaciones en paralelo	Multiple machines/VMs, one per agent	Mixture, according to each case

Note

Each agent is a machine. To run several processes at the same time you need several agents (several machines or VMs), each with its own Machine Key.

Multi-tenancy

Zoan Cloud is multi-tenant: it hosts multiple organizations on the same instance, but completely isolated from each other. Each tenant has its own environments, agents, processes, users and credentials. Tenant resolution is done by subdomain:

acme.cloud.zoansoftware.com   →  tenant "acme"
otra.cloud.zoansoftware.com   →  tenant "otra"

One tenant’s data is never visible to another. See Tenant.

Security, in summary

• Agent authentication using a unique Machine Key per machine.
• Encrypted connections (HTTPS/WSS) and only outgoing from the agent.
• Aislamiento por tenant a nivel de datos y de subdominio.
• Credentials stored securely and resolved at runtime, without being exposed in playbooks or logs. See Credential Management.

Next steps

• Key Concepts — the complete vocabulary.
• Getting Started — install and connect your first agent.
• Windows installation — Agent and network details.