Connections — databases, ERP, CRM & email
Give SphereHarness a named door into your business systems, so chat can look up parts, check stock, read sales orders or send a report by email. The connections are set up and kept by your company; SphereHarness never stores or relays them.
How it works
A connection is a name (PartsDb, ERP, Email), the address of the system, how to sign in to it, and whether the assistant may change data through it. Users then ask in plain words:
- Where they are kept. In your company's connections store. It is part of the same service as your organisation's document index, on your own server, and users sign in to it the same way (Windows login, Microsoft Entra ID, or a shared key). A single user without such a server keeps the store on their own PC.
- How a call runs. The user's desktop agent asks the store for that one connection. The store checks the connection's allow list and, if the connection uses a company secret, sends the secret sealed to a key made for that one call. The desktop agent then connects directly from the PC to your database or API, keeps the secret in memory only, and wipes it afterwards.
- What SphereHarness sees. Nothing: not the definitions, not the secrets, not the queries or their answers.
- Secrets at rest are encrypted with Windows DPAPI: machine-scoped on the company server, and scoped to your Windows account in a single-user store.
Setting up the company store (IT)
The store comes with the document-index service. If your organisation already runs its document index on a server, the store is already there, at the same address, with the same sign-in. Nothing else to install.
- Install the document-index service on a Windows server (see Document index for IT) and choose how users sign in (
Rag:Auth:Mode=Windows,Entraor the key). - Set the connections admin password once, on the server itself:
It asks for the password (at least 12 characters) and keeps only a PBKDF2 hash. Five wrong tries lock it for 15 minutes.CADCoPilot.Rag.Server.exe --set-connections-admin-password - Optional: name the AD / Entra groups whose members may edit connections without the password:
A Windows group is"Rag": { "Connections": { "AdminGroups": [ "CONTOSO\\SphereHarness Connection Admins" ] } }DOMAIN\Groupor its SID; an Entra group is its object id or an app-role value. - Optional: let your SphereHarness organisation admins edit without a password:
The server then checks a 5-minute signed assertion with SphereHarness's public key only ("Rag": { "Connections": { "SphereHarness": { "Issuer": "https://sphereharness.io", "OrgId": 123 } } }/.well-known/company-admin-jwks.json). No SphereHarness secret is placed on your server, and nothing about your server is sent to SphereHarness.
The store is the file connections.db beside the index database (or Rag:Connections:Database). Back it up with the server. Secrets in it can only be read on that machine.
Adding and editing connections (connections admins)
In the desktop agent: Settings → Knowledge → Company connections…. The window shows which store you are editing and who you are editing as. If you are not yet an admin, type the admin password and click Sign in as admin.
- Pick a provider template (SQL Server, PostgreSQL, Business Central, Dataverse, Salesforce, HubSpot, Microsoft 365 mail, SendGrid, Google Sheets, generic REST, …) and fill in its fields. The JSON view shows the exact configuration; it never contains a secret.
- Choose the login method (below) and, for a company secret, type it. A stored secret is never shown again; leave the box empty to keep it.
- Leave Read-only ticked unless the assistant must change data. A writable connection still asks the user to confirm every write; a database also needs Allow database writes for the whole company.
- Optionally limit it with Allowed users / groups (one per line). Empty = everyone who can sign in to the store.
- Click Test from this PC: it connects exactly as a user's agent will. Then Save.
Every change is written to the store's audit log (who, what, when; never a secret value): Audit log… in the same window.
Login methods
| Method | What is stored | Use it for |
|---|---|---|
windows | Nothing secret | SQL Server with Windows authentication, intranet APIs with Negotiate: each user connects as themselves. |
userOAuth | Client id, tenant, scopes (no secret) | Microsoft Graph / Dynamics 365 / Business Central, Salesforce, Google: each user signs in once in the browser (below). |
companySecret | One company credential, encrypted | A database password, an API key, a bearer token, basic auth, or an OAuth client secret (authKind = bearer, apiKeyHeader, basic, oauthClientCredentials). HubSpot private apps and other APIs that only offer a key. |
none | Nothing | A public API, or a SQLite file on a share. |
Signing in with your own account (userOAuth)
For a userOAuth connection, each user signs in once: in the Company connections window, select the connection and click Sign in (my account), or just use it from chat — the browser opens the provider's sign-in page. The desktop agent uses the authorization-code flow with PKCE and a loopback address on your PC (http://localhost:<port>), with no client secret. The tokens are kept for your Windows account on that PC (DPAPI) and refreshed silently.
- Microsoft Graph, Dynamics 365, Business Central: register an app in Entra ID, platform Mobile and desktop applications, redirect URI
http://localhost, Allow public client flows = Yes, and the delegated permissions you need. The admin enters the client id and tenant. - Salesforce: a connected app with Require Proof Key for Code Exchange on and Require Secret for Web Server Flow off; its callback URL must be
http://localhost:<port>/with the same port entered in the connection. - Google: an OAuth client of type Desktop app. Google issues a client secret for desktop clients but treats it as not confidential; it may be entered in the connection's configuration.
- HubSpot and other providers that require a confidential client secret: use
companySecretwith a private-app token or API key.
Files: attachments, documents, downloads
A connection call can save its reply to a file instead of returning it as text. Ask for the attachment or document and the assistant calls the connection with saveTo (a full file path, or a folder — then the provider's file name is used). The bytes go straight to disk, unchanged; the answer is the saved path, its size, its type and its SHA-256. With a Microsoft 365 mail connection:
GET me/messages?$filter=hasAttachments eq true&$top=1— find the message;GET me/messages/{id}/attachments— list its attachments;GET me/messages/{id}/attachments/{attachmentId}/$valuewith saveToC:\Users\me\Downloads\— the file itself.
A reply that carries the file as base64 inside JSON (Graph's contentBytes) is decoded into the file with saveField = contentBytes.
- At most 200 MB per file. Nothing is kept when the provider answers with an error or the download stops.
- The target must be outside Windows, Program Files and SphereHarness's own settings folders. An existing file is replaced only when the request says overwrite.
- Without saveTo, a reply longer than 20,000 characters is cut — and says so, with the full length and that saveTo gets all of it.
- The assistant never opens Outlook or a web page to download a file a connection can fetch.
- A connection that runs through the SphereHarness server (ServerProxy, hosted AI only) returns at most 20,000 characters of text and no file; switch it to ClientDirect to save files.
Single user, no company server
When your document index is this PC (Settings → Knowledge), your connections live on your PC too, in the same folder as your local index, encrypted for your Windows account. You are their admin: no password, no server, nothing to configure anywhere else. Open Settings → Knowledge → Company connections… and add them.
Moving your connections from the SphereHarness website
Connections used to be set up on the website (Org portal → Connections). That page now only helps you move them:
- As organisation admin, open Org portal → Connections and click Download export (no secrets). The file holds names, types and configuration only.
- In the desktop agent, Company connections… → Import JSON…. The window lists the connections that need their secret entered again. An old allow list named SphereHarness users; enter your Windows or Entra users / groups instead.
- Enter the secrets, Test, Save.
- Back on the website page, tick the confirmation and click Delete the stored secrets. The definitions stay until your organisation is closed, so the export keeps working.
Good to know
- Names are what users say in chat — keep them obvious: PartsDb, ERP, Email.
- A refused call says why: not on the allow list, read-only, database writes off, or the user declined the write.
- A connection only reaches addresses under its own base URL.
- Disable a connection instead of deleting it to take it offline without losing the setup.