Get started
Core concepts
ConnXL is a small set of objects that nest cleanly: an organization owns add-ins, each add-in is served by an agent and split into environments, and each environment holds connections and functions. Understanding this hierarchy makes everything else obvious.
6 min read
Organization
Your tenant. Users, notification webhooks, and members live at the organization level. An organization contains many add-ins.
Add-in
An add-in is what you ship to your end-users: one entry in the Microsoft 365 admin center, one formula namespace, one taskpane. You serve it by running the connxl-agent binary on your own host — one agent per environment (see below). In the dashboard the add-in is the top-level thing you create, name, and switch between.
Environment
An add-in owns an ordered set of named environments — up to five, configured from the dashboard. A new add-in starts with a single Development environment.
-
Each environment runs its own agent — its own
connxl-agentprocess, authenticated via a one-time enrollment token exchanged for an mTLS client certificate scoped to that environment. It's the certificate that decides which environment an agent serves. An add-in with Development and Production environments is served by two agents, live in parallel, and one agent can scale to several replicas that share the environment's certificate and config. -
The lowest environment (Development) is the source — the only place where structure (functions, connection definitions, ribbon buttons, the taskpane) is created or edited.
-
Every other environment is a promote target: there you edit only environment-specific values — credentials, hosts, cache. Structural edits are rejected (the backend enforces this, not just the UI).
-
Promote copies the source's structure into a downstream environment while preserving that environment's own values, so you can move a change to QA or production without touching its credentials.
Connection
A pointer to one of your data sources — a database, an HTTP API, a cloud function, a remote file, or a cache. Connections are defined in the dashboard (credentials by secret:// reference) and resolved by the agent at execution time. See Connections for the full catalog.
Function
A function maps a connection to a formula your users type, e.g. =CONNXL.SALES.TOP_CUSTOMERS(10). Functions vary along two axes:
- Output shape — what the result looks like in the grid: a single value, a row, a table (spills to a range), or an entity (a linked data type with field accessors like
=A2.Price). - Execution model — sync (computed locally), async (the default; runs on the agent), or streaming (live-updating).
The dashboard / agent split
The dashboard is the config of record — it stores what your add-ins do and pushes changes to your agents over a streaming channel. The agent is the execution plane — it serves the add-in to Excel and runs every function call against your data. The dashboard talks only to this backend; it never talks to your agent directly, and it never touches your data sources.
The product invariant
Customer data never traverses our backend. Your credentials and your cell data stay inside your network — the only way to use ConnXL is to run an agent. The dashboard sees only metadata: latency, status, cache outcome, and SHA-256-hashed user emails.
Quickstart
Stand up a working Excel add-in that runs your own functions against your own data — without any of your spreadsheet data ever leaving your network. This walks the whole path, from signing up to typing your first =NAMESPACE.MODULE.FN(…) formula in a cell.
Glossary
Every ConnXL term in one place, with the one distinction people get wrong most often: an add-in is what you create, an agent is what runs it.