Install the add-in

Installing ConnXL means two things: running the agent on a host your Excel users can reach, and getting the generated manifest into Excel. The agent serves the add-in; the manifest just tells Excel where the agent lives.

Running the agent in production?

This page covers the minimum to get the agent up and the manifest into Excel. For service files, containers, upgrades, firewall rules and decommissioning, see Deploy and run the agent.

Run the agent

The agent is a single binary, connxl-agent, that you run on your own VM, container, or bare metal — in your own cloud or on-prem, inside your network. It reads its live configuration (functions, connections, secrets-by-reference) only from the backend — there is no YAML config file. A small set of files does sit on disk beside it: the TLS cert.pem/key.pem pair, and the static/ directory from the download (the taskpane shell and neutral logos the agent serves).

Download the configured agent from the environment's Agent page in the dashboard, under the Deploy tab (it's the whole page the first time this environment deploys). Click Download configured agent, pick your host's platform (Windows x64, Linux x64, or Linux arm64), and you get a binary with this environment's identity already embedded — the backend URL, the add-in and environment, and a fresh one-time enrollment token, all stamped into the download. There is nothing to configure: drop it on your host with the static/ directory beside it, add the TLS certificate below, and run it. On first boot it reads its own embedded identity, enrolls for its mTLS client certificate, and starts serving — no environment variables at all.

A configured download is unique — and revocable

Every Download configured agent stamps in its own fresh enrollment token, so each download is byte-unique (a release's SHA256SUMS cover the plain binaries, never a stamped one). If a configured binary leaks or a host is retired, click Regenerate on the same panel: it revokes every enrollment token for this environment at once — every previously downloaded configured binary and every hand-copied token — so none of them can enroll again. Agents that have already enrolled are unaffected: they authenticate with their mTLS certificate, and only a fresh enrollment needs a live token. Re-download to hand out a replacement.

Serve the add-in over HTTPS

Office add-ins must be served over HTTPS. Choose how the agent gets there with CONNXL_TLS_TERMINATION:

edge (the default) — the agent serves plain HTTP on :3000 and expects a TLS-terminating load balancer in front (an AWS ALB with an ACM certificate, nginx, Caddy, or a tunnel) on a DNS name you own. The agent holds no certificate, so it autoscales cleanly — the recommended production setup.
agent — the agent terminates TLS itself. Set CONNXL_TLS_TERMINATION=agent and place cert.pem and key.pem next to the binary. Use this for a single VM with no load balancer, or for local testing (mkcert issues a trusted cert).

Either way the agent listens on :3000. Office will not load an add-in over untrusted HTTP directly, so an edge agent exposed without a terminator in front fails visibly rather than serving insecurely.

terminalsh

# working directory holds: connxl-agent, static/  (cert.pem + key.pem only in agent mode)

./connxl-agent                                # default (edge): HTTP on :3000 behind your TLS-terminating load balancer
CONNXL_TLS_TERMINATION=agent ./connxl-agent   # agent terminates TLS with cert.pem/key.pem → https://<host>:3000

Reachability

Whatever host you choose must be reachable over HTTPS by every Excel client that will use the add-in — Excel fetches the taskpane and runs functions against the agent directly. The agent only makes outbound connections to this backend, so it sits comfortably behind NAT or a firewall.

The embedded token only bootstraps enrollment

The one-time token baked into a configured binary does exactly one thing: it lets the agent obtain its mTLS client certificate on first boot. After that the certificate — not the token — authenticates every request, forever. That is why Regenerate never disturbs an agent that has already enrolled, and why regenerating contains a leaked configured binary: the spent token can no longer earn a certificate. See Mutual TLS for the certificate lifecycle and the cloud-attestation alternative.

Deploy to a Linux host (AWS or anywhere)

On a real server, run the agent as a service so it restarts on boot and on crash. A configured binary carries its own identity, so the unit needs no CONNXL_* variables at all — just the working directory:

/etc/systemd/system/connxl-agent.serviceini

[Unit]
Description=connxl-agent
After=network-online.target

[Service]
WorkingDirectory=/opt/connxl-agent
ExecStart=/opt/connxl-agent/connxl-agent
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

connxl-agent and static/ live in /opt/connxl-agent (add cert.pem/key.pem too, and Environment=CONNXL_TLS_TERMINATION=agent, only if you want the agent to terminate TLS itself instead of running behind a load balancer). Then systemctl enable --now connxl-agent.

The agent only makes outbound connections to this backend and to your data sources, so a locked-down host needs no inbound ports open for the backend link. What does need to be reachable is the agent's :3000 HTTPS endpoint — Excel fetches the taskpane and runs functions against it directly, from wherever your users are. Give it a publicly-trusted certificate for the exact host in the manifest; on the web and on machines you don't manage, a self-signed cert will be rejected. Common patterns:

Reverse proxy / load balancer (nginx, Caddy, an AWS ALB with an ACM certificate) terminating TLS on a DNS name you own and forwarding to the agent's :3000.
A tunnel (e.g. Cloudflare Tunnel) that publishes the agent on a trusted HTTPS hostname without opening any inbound port — handy for a quick trial or an agent with no public IP.

Whichever you choose, set that public HTTPS URL as the environment's agent host (below) so the generated manifest points Excel at it.

Logs and cloud log collection

The agent writes to two places at once: a single rolling file in connxl-agent/logs/ beside the binary (connxl-agent_<date>.log, one file per day, auto-pruned after 7 days) and stdout. (The sibling connxl-agent/identity/ folder holds the enrolled mTLS identity — cert, key, and lease.) It does not ship logs to CloudWatch or any cloud service itself — that's the host's job, and stdout is the integration point every platform already understands:

Containers (ECS/Fargate, Cloud Run, GKE, Azure Container Apps): the runtime captures stdout for you — the awslogs driver → CloudWatch, and the equivalents → Cloud Logging / Azure Monitor — with zero extra config. The on-disk logs/ files are redundant here (no persistent disk), so ignore them.
Bare VM (EC2 / GCE / Azure VM under systemd or a Windows Service): nothing reaches the cloud automatically. Install that platform's log agent — the CloudWatch Agent, GCP Ops Agent, or Azure Monitor Agent — and point it at either the process's stdout/journald stream or the logs/*.log files.

Set json format for log shippers

When a log service is going to parse the stream, run the agent with CONNXL_LOG_FORMAT=json (see the environment variables below). Each line becomes one JSON object — {ts, level, category, msg} — so CloudWatch/Cloud Logging/Azure Monitor index the fields instead of treating every line as opaque text. Leave it unset (text) for human tailing.

Advanced: configure identity with environment variables

The configured download is the easy path, but the agent still reads its identity from CONNXL_* environment variables when you set them — the right choice for containers, Kubernetes, or any IaC/automation pipeline where a stamped download doesn't fit. Environment variables always win: any CONNXL_* value you set overrides the matching field embedded in the binary, so you can start from a raw (unconfigured) binary — grab one under Advanced / manual setup on the Deploy panel — or override individual fields on a configured one.

Field	Type	Description
`CONNXL_BACKEND_URL`Required	`URL`	This backend's public host — where the agent pulls its config and pushes telemetry.
`CONNXL_ENROLL_TOKEN`Required	`string`	A one-time enrollment token, revealed once when you click Regenerate for this environment. The agent exchanges it for its own mTLS client certificate on first boot, then authenticates with that certificate from then on.
`CONNXL_MTLS_CERT`Required	`path`	Path where the agent stores the client certificate it enrolls for — you pick the location, the agent creates the file. Not the same pair as cert.pem/key.pem above.
`CONNXL_MTLS_KEY`Required	`path`	Path for the matching private key. See Mutual TLS for the full lifecycle.
`CONNXL_DATA_DIR`Optional	`path`	Base folder for everything the agent writes to disk — its enrolled identity (identity/) and its logs (logs/). Absolute or relative to the working directory. Defaults to a connxl-agent/ folder beside the binary; set this to keep agent state on a specific mount. The path overrides above still win for those individual files.

No token? Enroll with the agent's cloud identity instead

On AWS, GCP, or Azure, the agent can enroll with no token at all using its instance identity — set CONNXL_ENROLL_ATTESTATION (plus CONNXL_ADDIN_ID/CONNXL_ENV_ID) instead of CONNXL_ENROLL_TOKEN. See Mutual TLS.

Point Excel at your agent host

On your add-in's page, set the agent host (override it per environment in the environment's settings). ConnXL folds that host into every URL in the generated manifest — the taskpane, the functions metadata, and every image — so Excel always talks to your agent and never to ConnXL.

Enter the domain only — addin.your-company.com, optionally with a port. The https:// is fixed and shown as a prefix on the field: Office only loads an add-in over HTTPS, localhost included, so the scheme is not a choice.

Download or copy the manifest

From the same page, download the generated manifest. ConnXL emits both the classic XML manifest and the unified JSON manifest — pick the one your Office version needs. You can also copy the manifest URL, which is the authoritative source for centralized deployment.

It's a manifest, not a binary

There is no one-click add-in binary and no Office Store listing. The download is a small manifest file that registers your agent-hosted add-in with Excel.

Get it into Excel

There are two ways to install, depending on who it's for:

Sideload — for yourself or a small team during setup. Register the manifest locally and the add-in appears on the ribbon. Microsoft's sideloading guide covers each platform.
Centralized M365 deployment — for rolling out to your whole organization. Your Microsoft 365 admin deploys the add-in from the admin center using the manifest URL, and it lands for every assigned user.

When you have to re-deploy

Most changes apply live — editing functions, connections, the taskpane, or templates flows to the agent over its config channel with no redeploy. Only changes that alter the manifest itself — the add-in icon, adding/removing/relabelling a ribbon button, or the custom tab name — require users to re-install the manifest.

Environment variable reference

Everything the agent reads at startup. A configured download supplies its own identity, so on that path you need none of these; they are the manual / automation path, and any value you set here overrides the matching field embedded in a configured binary. CONNXL_BACKEND_URL plus an enrollment credential — CONNXL_ENROLL_TOKEN, or CONNXL_ENROLL_ATTESTATION with CONNXL_ADDIN_ID/CONNXL_ENV_ID — plus CONNXL_MTLS_CERT/CONNXL_MTLS_KEY (where the issued certificate lands) is the minimum for wiring identity by hand; the rest are optional. The agent listens on port 3000. By default (CONNXL_TLS_TERMINATION unset or edge) it serves plain HTTP there behind a TLS-terminating load balancer — no cert.pem/key.pem required; set CONNXL_TLS_TERMINATION=agent to have it terminate TLS itself with the cert.pem / key.pem pair beside the binary (that pair is never an environment variable).

Field	Type	Description
`CONNXL_BACKEND_URL`Required	`URL`	This backend's public host — where the agent pulls its config and pushes telemetry.
`CONNXL_TLS_TERMINATION`Optional	`edge \| agent`	How the inbound Excel-facing listener on :3000 handles TLS. Default edge: the agent serves plain HTTP and a TLS-terminating load balancer in front handles HTTPS (no cert.pem/key.pem needed). agent: the agent terminates TLS itself with cert.pem/key.pem beside the binary — the single-VM / no-load-balancer / local case. This is separate from the agent-to-backend mTLS, which is always on.
`CONNXL_MTLS_CERT`Required	`path`	Path where the agent stores the client certificate it enrolls for (you pick the location — the agent creates the file). See Mutual TLS.
`CONNXL_MTLS_KEY`Required	`path`	Path for the matching private key.
`CONNXL_ENROLL_TOKEN`Conditional	`string`	One-shot enrollment token that lets a fresh agent obtain its mTLS certificate at first boot — the sole agent-auth mechanism (there is no more static API key). Required unless enrolling via CONNXL_ENROLL_ATTESTATION. See Mutual TLS.
`CONNXL_ENROLL_ATTESTATION`Conditional	`aws \| gcp \| azure`	Use the cloud instance-identity document as the enrollment credential instead of a token. Required unless CONNXL_ENROLL_TOKEN is set.
`CONNXL_ADDIN_ID`Conditional	`id`	The add-in this agent enrolls against. Required iff CONNXL_ENROLL_ATTESTATION is set — not read on the token path.
`CONNXL_ENV_ID`Conditional	`id`	The environment this agent enrolls against. Required iff CONNXL_ENROLL_ATTESTATION is set — not read on the token path.
`CONNXL_ZONE`Optional	`string`	Free-form placement label (a rack, a datacenter, an availability zone). Reported with health snapshots and shown on the agent health page.
`CONNXL_REGION`Optional	`string`	Free-form region label, reported alongside the zone.
`CONNXL_REPLICA_ID`Optional	`string`	Optional label identifying this replica in heartbeats and aggregated logs. Useful when you run several agents behind a load balancer and the machine hostname is opaque (a container or pod id). Defaults to the machine hostname.
`CONNXL_HEARTBEAT_SECONDS`Optional	`int`	Heartbeat interval in seconds. Default 30, clamped to a 60 max — the backend marks an agent offline after ~90 s of silence, so a longer interval would flap a healthy agent.
`CONNXL_STATE_DIR`Optional	`path`	Directory where the agent persists its runtime state across restarts. Defaults to a state/ directory next to the binary.
`CONNXL_SECRETS_TTL_SECONDS`Optional	`int`	How long resolved secret references are cached, in seconds. Default 300; 0 or negative disables the cache. Lookup errors are never cached.
`CONNXL_SECRETS_AWS_REGION`Optional	`string`	Default region for AWS-backed secret references. A ?region= on the reference itself wins; with neither set, the AWS SDK default chain applies.
`CONNXL_SECRETS_AWS_ENDPOINT`Optional	`https URL`	Custom endpoint for AWS-backed secret references (a VPC endpoint, a FIPS endpoint, or an emulator). Must be https or a loopback address — anything else is ignored with a warning, because setting an endpoint also skips the credential chain and a plaintext one would carry secret names and values in the clear.
`CONNXL_SECRETS_GCP_ENDPOINT`Optional	`https URL`	Custom endpoint for GCP Secret Manager references (a private or emulated Secret Manager). Must be https or a loopback address. When set, Application Default Credentials are skipped. Leave unset for the real service.
`CONNXL_SECRETS_AZURE_ENDPOINT`Optional	`https URL`	Custom endpoint for Azure Key Vault references (a private or emulated vault). Must be https or a loopback address. When set, DefaultAzureCredential is skipped. Leave unset for the real service.
`CONNXL_LOG_LEVEL`Optional	`debug \| info \| warn \| error`	Minimum severity written to the logs. Default info; debug adds verbose lines; warn keeps failures and retryable problems; error keeps only terminal failures — it also hides a failed heartbeat or re-enrolment, so prefer warn when reducing noise.
`CONNXL_LOG_FORMAT`Optional	`text \| json`	Log line format on disk and stdout. Default text (human-readable); json emits one JSON object per line ({ts, level, category, msg}) for log shippers.

Connections

Wire the agent to your data sources before you build functions.

Using functions in Excel

The namespace, the taskpane, cell references, spills, and live updates.

Install the add-in

Connections

Using functions in Excel

On this page