Deploy and run the agent

The agent is one self-contained executable. It has no installer, no runtime dependency, no database of its own, and it reads its entire configuration from environment variables plus the config snapshot it pulls from ConnXL. Everything below assumes you already created an add-in and an environment in the dashboard — the Agent page's Deploy tab is where you download a binary that is already stamped with its identity.

Download and verify the binary

Deploy → Download configured agent gives you a binary with its backend URL, add-in ID, environment ID and a fresh enrollment token already embedded, so it runs with zero environment variables. Platforms: Windows x64, Linux x64, Linux arm64.

Each download is published alongside a SHA256SUMS file. Verify before you run it:

# Linux / macOS
sha256sum -c SHA256SUMS --ignore-missing

# Windows PowerShell
(Get-FileHash .\connxl-agent.exe -Algorithm SHA256).Hash -eq (Get-Content .\SHA256SUMS | Select-String 'connxl-agent.exe').ToString().Split()[0]

Confirm what you have at any time:

connxl-agent --version     # prints the build version
connxl-agent --licenses    # prints third-party notices

Run it as a service

The agent runs in the foreground and logs to stdout, so any service manager works. Give it a dedicated user and a stable working directory — it writes its enrolled identity there.

Linux (systemd)

[Unit]
Description=ConnXL Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=connxl
WorkingDirectory=/opt/connxl
ExecStart=/opt/connxl/connxl-agent
Restart=always
RestartSec=5
Environment=CONNXL_DATA_DIR=/var/lib/connxl
# TimeoutStopSec must exceed the agent's 10s in-flight request drain.
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now connxl-agent
sudo systemctl status connxl-agent

Windows (service)

The binary is a plain console application, so register it with sc.exe or a service wrapper such as NSSM:

# Using NSSM (handles stdout redirection and restarts)
nssm install ConnXLAgent "C:\Program Files\ConnXL\connxl-agent.exe"
nssm set ConnXLAgent AppDirectory "C:\Program Files\ConnXL"
nssm set ConnXLAgent AppEnvironmentExtra "CONNXL_DATA_DIR=C:\ProgramData\ConnXL"
nssm set ConnXLAgent AppStdout "C:\ProgramData\ConnXL\logs\stdout.log"
nssm start ConnXLAgent

Run it in a container

There is no published image — build a minimal one around the Linux binary. The agent needs CA certificates for outbound TLS and a persistent volume for its identity, or it re-enrolls on every restart.

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY connxl-agent /usr/local/bin/connxl-agent
ENV CONNXL_DATA_DIR=/var/lib/connxl
VOLUME /var/lib/connxl
EXPOSE 3000
ENTRYPOINT ["/usr/local/bin/connxl-agent"]

Kubernetes. Run it as a Deployment behind a Service, with the enrollment token from a Secret. Use a liveness probe only — see the health-endpoint warning in section 6.

spec:
containers:
  - name: connxl-agent
    image: your-registry/connxl-agent:0.1.0
    ports:
      - containerPort: 3000
    env:
      - name: CONNXL_BACKEND_URL
        value: https://api.connxl.com
      - name: CONNXL_ADDIN_ID
        value: "<add-in id>"
      - name: CONNXL_ENV_ID
        value: "<environment id>"
      - name: CONNXL_ENROLL_TOKEN
        valueFrom:
          secretKeyRef: { name: connxl-agent, key: enrollToken }
    livenessProbe:
      httpGet: { path: /healthz, port: 3000 }
      initialDelaySeconds: 10
      periodSeconds: 30
    terminationGracePeriodSeconds: 30

Environment variables

A stamped binary needs none of these; every variable still overrides its stamped value. Only the identity group is required on an unstamped binary.

Identity and backend

Listener and TLS

Storage and identity files

Logging

Secrets

Network requirements

Every connection to ConnXL is initiated by the agent outbound. Nothing needs to reach the agent from the internet, and no inbound firewall rule is required for ConnXL itself.

Outbound — allow to your ConnXL API host on TCP 443:

Two of these — the SSE config stream and the WebSocket control channel — are long-lived connections. Middleboxes that kill idle connections will cause repeated reconnects; the agent recovers, but the dashboard will flap.

Inbound: your Excel users (and your load balancer) must reach the agent on CONNXL_LISTEN_ADDR, default port 3000.

Also allow: your own data sources, and — only if you use cloud-identity enrollment — the instance metadata endpoint (169.254.169.254).

Health checks and monitoring

The agent serves GET /healthz on its listen address. It returns 200 ok whenever the process is running.

For real health, use the dashboard: the environment's Agent page shows each replica's CPU, memory and disk with a 24-hour timeline, the last heartbeat, and the config version actually applied. The backend flags an agent offline after roughly 90 seconds without a heartbeat, and alerts can notify you — see Alerts.

Upgrade to a new version

The agent never updates itself. When a replica reports a version older than the latest release, the dashboard flags it and can raise an Update available notification, but nothing is downloaded or replaced without you. An upgrade is: put the new binary in place and restart.

Because there is no deregistration handshake with your load balancer, take the instance out of rotation yourself first — /healthz will keep returning 200 right through a shutdown, so it cannot signal the drain for you.

1. Remove the replica from the load balancer.
2. Send drain from the Agent page. This tears down streaming subscribers so they reconnect elsewhere; it does not stop the listener or exit.
3. Stop the service (SIGTERM, or systemctl stop). In-flight requests get up to 10 seconds to finish, so allow at least 30 seconds of stop timeout.
4. Replace the binary and start the service again.
5. Confirm the new version on the Agent page, then return the replica to rotation.

With more than one replica, do this one at a time and the environment stays up throughout.

What the agent stores on disk

Cached function results are held in memory, or in Valkey/Redis when the environment configures an external cache — never on disk.

You do not need to back any of this up. If the data directory is lost, the agent re-enrolls automatically on the next boot and carries on, as long as its enrollment token (or cloud attestation, or stamped identity) is still in its environment. The only cost is a new certificate and a fresh log history. You need a new token only if an admin has since clicked Regenerate.

Sizing and scaling

The agent is a lightweight proxy: it holds no dataset, and its work is dominated by waiting on your data sources. A small instance — 1 vCPU and 512 MB of memory — comfortably runs a typical environment, and disk use is limited to a week of logs.

Scale out, not up. Add replicas behind a load balancer when you need throughput or redundancy:

• All replicas of an environment share one enrollment token and appear individually on the Agent page.
• No session affinity is required — the agent keeps no per-user state between requests.
• Size for concurrency at your data sources first; the SQL pool defaults (20 open connections per engine, per replica) multiply by replica count.

Retire an agent

To decommission a host cleanly:

1. Take it out of rotation and confirm traffic has moved to another replica.
2. Stop the service and disable it from starting at boot.
3. Evict the replica from the environment's Agent page. This block-lists it so it cannot reconnect even if the process comes back — the reliable way to cut off a host you no longer control.
4. Delete the data directory to destroy the private key on disk.
5. If you are retiring every agent for that environment, click Regenerate on the Deploy tab so the old enrollment tokens stop working.