What happens while an Agent is disconnected?

Queries against its connections will not run anywhere - Query Builder, Excel, Google Sheets, the REST API or an AI assistant - and scheduled refreshes pause. Changes you save in the browser meanwhile are held and applied the moment it reconnects.

Setup · Windows

Install the Query Streams Agent on Windows

Q: Where do I add, edit or delete connections?

In your browser, on the Data Agents page at my.querystreams.com/data-agents, using Add connector. Changes usually reach your Agent within seconds; if it has been offline they apply as soon as it reconnects. You do not need to touch the Agent machine to add or change a connection.

Q: Does my data get copied to Query Streams?

No. Your database stays where it is. When you run a query the Agent reads your database and returns only the rows that query asked for, and your database password stays on the Agent machine.

Q: Do I need to open a port or change our firewall?

Normally no. The Agent makes an outgoing connection, the same way a web browser does, so nothing needs to accept incoming traffic from the internet.

Q: Do I have to keep updating the Agent?

No. When a new version is published it is pushed to your Agent over the connection it already has open, so it usually updates within moments and restarts itself. It also checks on its own once a day as a safety net.

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

Stuck at any point? Just ask us. Open Support in Query Streams (top-right menu → Support) and send us a message. Real people read it, and “I don’t know what this screen is asking for” is a perfectly good question.

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 Windows PC or server

It needs to stay switched on when people are running queries. A machine that sleeps at night will simply be unavailable until it wakes.

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.

Where should it go? Put the Agent on a machine that can already open your database today — often the database server itself, or any PC on the same office network. If you can reach the data from that machine, so can the Agent.

Install it in four steps

Download and run the installer

Sign in at my.querystreams.com/download and choose the Windows download. Run the file and accept the prompts.

The Agent installs itself as a Windows service, which is a fancy way of saying it starts on its own whenever the machine 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.
Sign in with your key

When the Agent is installed, open its page on that machine:
On the machine 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.
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.
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 set things up in the browser. The Agent does the reading, inside your network. Only the rows your query asked for travel back — and the Agent always dials out, so nothing needs to be opened up to the internet for it to work.

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.

Query Streams, in your browser

Everything you’ll actually do, from anywhere:

Adding, editing and removing connections
Testing a connection
Choosing which databases to include
Setting how often data refreshes
All Agent settings

The Agent’s own page

One job, and you may never need it:

Checking why the Agent can’t reach Query Streams

If your Agent shows as offline in the browser and you can’t see why, open localhost:1823 on that machine. The badge in its top-left corner tells you straight away (see what the four states mean), and it can see the network from where it’s standing — which your browser can’t.

The Agent is becoming fully hands-off. It’s designed to be something you install once and forget. Every operation is moving into Data Agents in the browser, and the only thing the Agent’s own page will keep is helping you work out why it can’t reach Query Streams. So if a guide or a colleague tells you to go and configure something on the Agent machine, check the browser first.

If you’ve read an older version of this guide: it said connections had to be set up on the Agent’s own page and not in the browser. That’s no longer true — the browser is now the place to do it. Anything you set up the old way still works, and you’ll find it waiting for you in Data Agents.

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:

Connected to Query Streams

Connecting to Query Streams Reconnecting to Query Streams

Disconnected from Query Streams

Connecting and reconnecting look the same — a moving band of colour, meaning “working on it”. A steady green glow means connected. A flat, dim badge means it isn’t.

The little light isn’t a button. It only reports status — clicking it does nothing. The Connect, Reconnect and Disconnect controls are named buttons on the Connection panel further down the page, which is deliberate: an unlabelled light that quietly took your Agent offline when clicked was a trap worth removing.

All goodConnected to Query Streams

Everything’s working. Your queries will run and any changes you make in the browser will reach this Agent within seconds. Nothing to do.

Starting upConnecting to Query Streams

Normal for a few seconds after the machine boots or the Agent restarts. Give it a moment.

Working on itReconnecting to Query Streams

The link dropped and the Agent is putting it back by itself — usually a brief network blip, and it needs no help from you.

If it sits here for more than a few minutes, something on the network is blocking the way out. That’s worth a message to us.

Needs attentionDisconnected from Query Streams

While it’s in this state, nothing on this Agent works. It’s the Agent that does the actual reading, so if it can’t be reached, there’s nothing to do the work.

Check the machine is online, then press Reconnect on the Connection panel. If it won’t come back, it’s usually a firewall or proxy blocking outgoing traffic — send us a message and we’ll help you pin it down.

What stops while an Agent is disconnected. Everything that needs to touch its data:

Queries against its connections won’t run — in Query Builder, in Excel or Google Sheets, from the REST API, or from an AI assistant
Scheduled refreshes and automations for that data don’t happen
Its connections can’t be tested, browsed or refreshed from your browser
In Data Agents it shows as offline, and the figures you see are the last known ones rather than live

Nothing is lost, though. Changes you save in your browser while it’s away are held and applied the moment it reconnects — so you can carry on setting things up without waiting for it.

Getting in touch about a connection problem? The Connection panel on that page lists the four things that help us most. Copy them into your Support message and we can usually skip the back-and-forth:

Machine: which computer the Agent is on
Organization: which account it’s attached to
Agent version: which build it’s running
Connected since: when it last managed to connect

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:

Usually Within moments

The moment we publish an update we push it straight down the connection your Agent already has open. It updates in place and restarts itself.

If it was switched off Seconds after it reconnects

It asks whether it missed anything a few seconds after coming back online, then catches up.

Belt and braces Once a day, by itself

It also goes and checks once a day using its own outgoing connection — so even on a tightly locked-down network it stays current.

How to tell it’s keeping up. The Connection panel on the Agent’s page shows Agent version. Under normal conditions that tracks our current release by itself. If you notice it sitting well behind for days, something on the network is blocking the update path — that’s worth a message to us, because it’s not something the Agent can talk its own way out of.

When does a new connection start working?

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

Usually A few seconds

The Agent is running and up to date, so it picks up the change straight away. No restart.

If it’s switched off When it reconnects

Your change is saved safely and applies the moment that machine comes back online.

Older Agents At its next restart

Rare, since Agents update themselves. Query Streams tells you on screen if this applies to yours.

Common questions

Where do I add, edit or delete connections?

In your browser, on the Data Agents page — use Add connector. Changes usually reach your Agent within seconds. If the Agent has been offline, they apply as soon as it reconnects. You don’t need to touch the Agent machine to add or change a connection.

Does my data get copied to Query Streams?

No. Your database stays where it is. When you run a query, the Agent reads your database and returns just the rows that query asked for. Your database password stays on the Agent’s machine.

Do I need to open a port or change our firewall?

Normally no. The Agent makes an outgoing connection to us, the same way a web browser does. Nothing needs to accept incoming traffic from the internet.

Can I use more than one Agent?

Yes — a lot of organisations run one per site or per network. They all appear together in your account, so it doesn’t matter to the person writing a query which Agent holds which connection.

Do I have to keep updating it?

No — and there’s nothing to click. When we publish a new version it’s pushed to your Agent over the connection it already has open, so it usually updates within moments and restarts itself. It also checks on its own once a day as a safety net. You can see which version it’s on under Agent version on its Connection panel.

What if I get stuck halfway through?

Message us from Support inside Query Streams and tell us where you got to. If it’s easier, say which screen you’re looking at and what you expected to see — that’s usually enough for us to spot it.

Didn’t go to plan? That’s worth telling us. Open Support in Query Streams to message the team, or browse the Knowledge Base tab for more guides. If a step in this page didn’t match what you saw on screen, tell us that too — it means the guide needs fixing, not you.

Installing somewhere else?

Linux

macOS

Setup trouble?

Agent shows Offline, or Test connection and Browse are greyed out? Check that the Agent is online → Is the Agent online?