Skip to main content
Pipeline agents are lightweight processes you run inside your network. Planasonix orchestration reaches your private systems through an outbound-only tunnel the agent maintains, so you do not expose database ports to the public internet.

​
What agents are

An agent:
  • Registers with your Planasonix organization using a scoped enrollment token.
  • Opens a secure channel for command and metadata traffic; data moves according to the connectors you authorize.
  • Reports health, version, and connectivity diagnostics to the control plane.

​
Why you need them

Many enterprises keep sources on private RFC1918 networks, VPN-only segments, or behind firewalls that forbid inbound connections from SaaS IPs.
Databases, file shares, and internal APIs often have no route from the cloud. The agent initiates connectivity from inside, where those systems are reachable.
Agents complement the JDBC gateway and warehouse connectivity patterns: use agents when no stable public endpoint exists or when security review rejects inbound allow-lists.

​
Installation

1

Create an agent enrollment

In Platform → Pipeline agents, create an agent profile and copy the enrollment token and region endpoint your admin published.
2

Choose a host

Pick a Linux or Windows server with outbound HTTPS to Planasonix, stable DNS, and network path to your sources. Avoid laptops that sleep.
3

Install the binary or container

Run the installer script or pull the official container image; pass the token via secret manager or environment variable, never commit it to git.
4

Register as a service

Configure systemd, Windows Service, or your orchestrator so the agent restarts on failure and survives reboots.
5

Verify in the UI

Confirm the agent shows Connected and the expected version; assign it to connections that should route through it.
Run one agent per failure domain (for example per data center). You can register multiple agents for high availability; connections should list acceptable agent pools.

​
Health monitoring

The control plane tracks:
  • Last heartbeat and clock skew
  • CPU and memory samples where enabled
  • TLS and certificate expiry for the agent’s identity
  • Queue depth for pending work (when applicable)
Set alerts when an agent goes stale so scheduled jobs do not fail silently at hour-end.

​
Diagnostics

From the agent detail page you can:
  • Download recent logs (redacted) for support tickets
  • Trigger a connectivity probe to a hostname and port your policy allows
  • Compare effective configuration with the version pinned in the UI
Some deployments enable automatic restart policies or canary upgrades when health checks fail repeatedly. Your platform team defines what runs without human approval.
Plan breaking connector changes with agent upgrades; pin versions during critical business windows and roll forward in maintenance slots.

​
Connectivity troubleshooting

SymptomWhat to check
Agent never connectsOutbound firewall to Planasonix endpoints, proxy HTTP(S)_PROXY, corporate SSL inspection
Intermittent disconnectsLoad balancer idle timeouts, NAT session limits, host sleep or patching windows
Source timeouts from jobsDatabase listen addresses, security groups, and whether the agent host can telnet/nc the port
Auth failuresWhether credentials are scoped to the agent’s IP or require Kerberos/NTLM hops the agent cannot perform
Do not disable TLS inspection by installing broad trust roots unless your security team approves. Prefer allow-listing the agent’s pinned certificates.

JDBC gateway

Alternative path for JDBC-heavy estates.

Diagnostics

Platform-wide run and system diagnostics.