The ACTIVATE Agent
Every cluster that ACTIVATE works with runs a small background process called the ACTIVATE agent. The agent opens an encrypted connection from the cluster out to the platform and keeps it open. ACTIVATE then reaches the cluster through that connection: terminals, file transfers, sessions, job submission, and monitoring all travel over it.
Because the cluster dials out, it does not need a public IP address or an open inbound port for ACTIVATE to reach it. The cluster needs only an outbound HTTPS route to the platform, over the internet or a private path such as network peering or a VPN.
How the Connection Works
- When the cluster starts (or when it is connected), the agent on its login or controller node opens an outbound connection to the platform on port 443.
- The connection is encrypted with TLS. When the platform supports it, the agent uses QUIC over UDP 443 for a faster connection and falls back to a WebSocket over TCP 443 if UDP is blocked.
- The platform opens separate streams inside this one connection whenever it needs to reach the cluster, for example when you open a terminal or a session. Nothing on the cluster listens for inbound connections.
- If the connection drops, the agent reconnects on its own.
The agent on the controller node also coordinates the cluster's compute nodes, which connect to it over the cluster's private network rather than to the platform.
What Travels Over the Connection
| Feature | What the agent does |
|---|---|
Terminals and pw ssh | Carries SSH connections to the cluster when it is reached through the tunnel. See Logging In to the Controller. |
| Port forwarding and sessions | Forwards traffic to applications running on the cluster, such as VS Code, desktops, and tunnel sessions. |
| File transfers | Moves files between the cluster and the platform. |
| Workflows and jobs | Submits and cancels scheduler jobs and runs workflow steps on the cluster. |
| Monitoring | Reports node health, resource usage, and scheduler information. |
| Updates | Receives agent upgrades from the platform. |
How the Agent Gets onto a Cluster
How the agent is installed depends on the type of compute resource:
| Resource type | How the agent is installed | How it signs in |
|---|---|---|
| Cloud cluster | Automatically. ACTIVATE installs and starts the agent as a system service while it provisions the cluster. There is nothing to install yourself. | A credential issued by the platform when the cluster is provisioned |
| Existing cluster (Auth method: User workspace) | Automatically. When you connect, your user workspace signs in to the cluster over SSH, copies the agent over, and starts it under your cluster account. | Approved by you as the cluster owner; it acts as you |
| Existing cluster (Auth method: PW CLI) | You run the command shown on the cluster page (pw agent connect <cluster>) on the cluster's login node, and approve the node in your browser. Keep it running while you use the cluster. | Approved by you as the cluster owner; it acts as you |
| Managed cluster | An administrator registers each node with a registration token (sudo pw agent register --token ... --systemd). See Register the Pilot Node. | A node-specific credential created at registration |
On cloud clusters and managed cluster nodes, the agent runs as the pw-agent system service. To check it from the node, run:
sudo systemctl status pw-agent
sudo journalctl -u pw-agentAgents that act on your behalf on existing clusters appear in Settings > Connected apps. Disconnect one there to revoke its access.
When ACTIVATE Connects Directly Instead
The agent connection is always available, but ACTIVATE can also connect straight to a cluster's SSH server (TCP port 22) when that route is reachable:
- Cloud clusters with a public IP address: SSH goes directly to the controller's public address on port 22.
- Cloud clusters on a network peered with the platform: ACTIVATE connects to the controller's private address directly.
- Cloud clusters on a private, unpeered network: all traffic goes through the agent connection. No inbound port is needed.
- Existing clusters: an administrator chooses through the Platform routing setting whether every existing cluster routes through the platform, or only listed hosts. Clusters on a private address, clusters behind a jump host, and PW CLI clusters always use the agent connection.
- Managed clusters: sessions and terminals use the registered node's tunnel when it is connected, and can fall back to direct SSH where it is configured. See How Access Works.
If your security policy does not allow inbound SSH, place the cluster on a private network that still has an outbound route to the platform (for example, through a NAT gateway). All access then goes through the agent.
Network Requirements
At minimum, the cluster's login or controller node needs:
| Direction | Destination | Port | Purpose |
|---|---|---|---|
| Outbound | ACTIVATE platform hostname | TCP 443 | Agent connection (WebSocket over TLS), API calls, and heartbeats |
| Outbound (optional) | ACTIVATE platform hostname | UDP 443 | Faster QUIC transport for the agent connection |
Allow inbound TCP port 22 only if you want the direct SSH routes described above. Administrators who self-host ACTIVATE can find the full port list in the Port Reference.
Troubleshooting
- A cluster is running but you can't open a terminal or session. Confirm that the cluster's login or controller node can reach the platform hostname on TCP 443. Proxies that block WebSocket upgrades will stop the agent from connecting.
- The connection is slower than expected. Allow outbound UDP 443 so the agent can use QUIC. If UDP is blocked, the agent keeps working over TCP 443.
- A PW CLI cluster shows as disconnected. The
pw agent connectcommand must keep running on the login node. Run it again and approve the node. - An agent is out of date. Platform administrators can set a minimum agent version; agents older than it can't connect, and already-connected agents below it are disconnected. On a PW CLI cluster, install the latest
pwCLI and connect again.