Setup · macOS

Install the Query Streams Agent on macOS

The Agent is a small program that sits beside your data and does the connecting. Install it once, then set everything else up from your browser.

About 10 minutes No coding needed Your data stays put

Query Streams lets you pull live data out of your databases and business apps — into Excel, Google Sheets, reports, or an AI assistant — without copying it anywhere first. To do that, it needs one small helper program running somewhere that can already reach your data. That helper is the Agent.

What you’ll need before you start

A Mac that stays awake

It needs to be awake when people are running queries, so it is worth checking the energy settings. Runs natively on Apple Silicon (M1–M4) and on Intel Macs.

Your sign-in key

A one-off code that ties this Agent to your organisation. You’ll find it in Query Streams on the Download page, right next to the installer.

Your database details

The server name, the database name, and a username and password that can read it. If someone else manages your database, this is the bit to ask them for.

Install it in four steps

1. Download and run the installer

   Sign in at my.querystreams.com/download and choose the macOS download — there are native Apple Silicon and Intel builds. Download the build that matches your Mac, then install it with a few lines in Terminal — you’ll need an administrator password.

   Open Terminal (press ⌘ Space and type “Terminal”) and paste in the lines for your Mac. Not sure which one you have? Apple menu › About This Mac: Chip: Apple M… means Apple Silicon, Processor: Intel… means Intel.

   Apple Silicon (M1 – M4)

   cd ~/Downloads
   mkdir -p querystreams-agent
   tar -xzf querystreams-agent_*_osx-arm64.tar.gz -C querystreams-agent
   cd querystreams-agent
   sudo ./install.sh

   Intel Mac

   cd ~/Downloads
   mkdir -p querystreams-agent
   tar -xzf querystreams-agent_*_osx-x64.tar.gz -C querystreams-agent
   cd querystreams-agent
   sudo ./install.sh

   The * stands in for the version number, so you don’t have to type it. If you’ve downloaded more than one version into that folder, type the full file name instead.

   sudo asks for your Mac’s password. Nothing appears as you type — that’s normal; press Return when you’re done.

   If you downloaded with Safari, it may have already unpacked the file into a folder named after the download (Safari does this when Open “safe” files after downloading is on). In that case the tar line will say it can’t find the file; instead, go into that folder and run the installer from there:

   If Safari already unpacked it

   cd ~/Downloads/querystreams-agent_*_osx-*
   sudo ./install.sh

   Then check it’s running — you should see a line ending in com.querystreams.agent:

   Check the service

   sudo launchctl list | grep querystreams

   If nothing comes back, the log is at /usr/local/querystreams/agent/logs/agent-stdout.log — attach it to a support request and we’ll take it from there. Once it’s installed you can delete the querystreams-agent folder in Downloads.

   The Agent registers itself as a background service, which is a fancy way of saying it starts on its own whenever the Mac boots. You don’t need to remember to launch it, and this is the only time you’ll download it — it updates itself from here on.

2. Sign in with your key

   When the Agent is installed, open its page on that machine:

   On the Mac you just installed it on

   http://localhost:1823

   Paste in your sign-in key. Look at the badge in the top-left corner: once it reads “Connected to Query Streams” with a green dot, you’re done here. That’s the Agent introducing itself to your account — and it’s the last thing you need to do on this machine.

   The page itself will tell you the same thing: “This agent runs your connections locally — day-to-day management happens in the Query Streams Portal.” That’s your cue to close it and carry on in your browser.

3. Add your first connection — from your browser

   Now go back to Query Streams in your browser and open Data Agents (it’s under Data in the top menu). Your new Agent will be listed there. Click Add connector and follow the questions: pick what kind of database or app it is, then fill in the details you gathered earlier.

   Open Data Agents

   You can test the connection before you save it, so you’ll know straight away whether the details are right rather than finding out later. Query Streams also suggests sensible settings for common databases, and adds a small set of ready-made example queries so you have something to run immediately.

   Once it’s saved, Query Streams takes a look around your database and notes down what’s in it — the tables, the columns, how they relate to each other. That’s what fills in the list you pick from in Query Builder, and it’s how Nova can answer “how many orders did we ship last month?” without you naming a single table. You don’t switch it on and there’s nothing to configure; it refreshes itself on a schedule so it keeps up as your database changes.

   It reads the shape, not the contents. This step is about table and column names, not your rows. On a large database it can take a few minutes to finish — you don’t have to wait around for it, and you’ll see when it’s done on the connector in Data Agents.

   Your password never leaves that machine. When you save a connection, the details travel to your Agent over an encrypted link and the credentials are stored there, on your own computer — not with us.

4. Run your first query

   The quickest route: press “Start a query” on the last screen of the connector setup. That opens Query Builder with your new connection already selected, so there’s nothing to go and find. You can also get there any time from the top menu.

   From there, run one of the ready-made example queries, write your own, or just ask Nova — our assistant — a question in plain English and let it write the query for you.

   When you save a query, it becomes reusable everywhere: refresh it inside Excel or Google Sheets, put it on a schedule, share it with a colleague, hand it to an AI assistant, or turn it into a web link another system can call.

   Open Query Builder Get the Excel & Sheets add-in

How the pieces fit together

You manage everything from the browser

Once the Agent is installed and signed in, you shouldn’t need to go back to that machine. Everything — connections, which databases to include, how often data refreshes, all the Agent’s own settings — is managed from Data Agents in your browser, from wherever you happen to be.

Is the Agent talking to Query Streams?

That badge in the top-left corner of the Agent’s page is the answer to almost every “why isn’t this working?” question. It always says one of four things, and the wording tells you exactly where you stand. This is what you’re looking for:

It keeps itself up to date

You install the Agent once. You won’t be asked to download it again, and there’s no “update available” nagging to stay on top of — when we release a new version, your Agent takes care of it on its own, and usually within moments.

It has three ways of finding out, so an update doesn’t get missed:

When does a new connection start working?

Almost always within a few seconds. The exact answer depends on your Agent:

Reading files on a network share

If a connector needs a file or folder on a network share, mount the share on this Mac before you add the connector. Mount it from Terminal with sudo, in a folder under /Volumes, so the Agent, which runs as a system background service, can see it. Share logins stored in the Portal are used by Windows Agents only. In the connector you can keep the \\server\share path, which the Agent maps onto the mount, or type the mount path directly. If the share isn’t mounted, Test connection says it is not mounted and shows the exact command to run.

How to mount a share for the Agent on a Mac

Common questions

Installing somewhere else? Windows Linux