What Linux distributions does the Query Streams Agent support?

The .deb package supports Ubuntu 20.04+, Debian 11+. The .tar.gz with install.sh works on any Linux x86-64 distribution including RHEL 8+, CentOS Stream, Fedora, and Amazon Linux 2.

Does the Query Streams Agent require opening firewall ports on Linux?

No. The agent only makes outbound HTTPS connections on port 443. No inbound firewall rules are required.

How to Install the Query Streams Agent on Linux

9 min read

Linux Network Agent

Install Query Streams on Linux

Run the outbound-only Query Streams Network Agent on Ubuntu, Debian, RHEL, or any x86-64 Linux server. One install script registers it as a systemd service. Use the local Agent dashboard at http://localhost:1823 to register the Agent and manage data connectors, then build saved queries in the Query Streams portal for Excel, Google Sheets, automation, REST APIs, MCP, and Nova AI.

Local connector setup No inbound firewall ports Runs as a systemd service

bash — user@ubuntu

$tar -xzf querystreams-agent_x.x.x_linux-x64.tar.gz

$sudo bash install.sh|

>[5/5] Service is running.

>Web UI: http://localhost:1823

querystreams-agent.service active (running)

Installing on a different OS?

Windows

macOS

See everything Query Streams can do after the Linux Agent is online Get Started Free

Connectors

+ APIs

Live Data

Run saved SQL directly from spreadsheets

Excel Sheets

BI & AI Analytics

Ask Nova questions over connected data

Meet Nova

Database REST API

Turn saved queries into secure endpoints

Build an API

+more

Automation

Schedule syncs and push live results

Explore

+more

API to SQL

Query SaaS APIs with SQL

Explore

AI Database MCP

Let AI tools query connectors directly

Connect AI

Query Streams is a secure, real-time data access platform that lets Linux server teams share live database results with Excel, Google Sheets, automations, MCP-compatible AI tools, and partner-ready REST APIs. Learn more at QueryStreams.com and sign up for free to install your first Linux Agent.

This guide covers installing the Agent on Ubuntu, Debian, and RHEL-based Linux distributions. The package includes a one-command install script that creates a dedicated querystreams service user, copies files to /opt/querystreams/agent/, and registers a systemd service that starts automatically on boot and self-updates silently. Add your data connectors inside the local Agent dashboard, then use the Query Streams portal to build your first saved query.

Before You Start

Supported distributions

Ubuntu 20.04+ and Debian 11+ via the .deb package, or RHEL 8+, CentOS Stream 8+, Fedora 36+, and Amazon Linux 2 via the universal .tar.gz archive. x86-64 (AMD64) only.

sudo / root access

Required to run the install script, create the dedicated service user, and register the systemd unit. The Agent itself runs as a non-root querystreams account afterward.

Outbound HTTPS

The Agent needs outbound HTTPS access on port 443 to Query Streams cloud services. No inbound firewall rule is required.

Database network access

Install the Agent on a Linux server in the same network, VPC, or routable environment as your database or API source.

Step 1: Download the Linux Agent

Sign in to my.querystreams.com/download.
Choose Linux from the Agent download options.
Download the .deb package (Ubuntu/Debian) or the .tar.gz archive (RHEL, CentOS, Fedora, Amazon Linux, or any other distro).
Copy your organization authentication key from the same download page. You will use it when the local Agent dashboard opens. If installing from a different machine, transfer the file first: scp querystreams-agent_x.x.x_linux-x64.tar.gz user@your-server:/tmp/

Step 2: Run the Install Script

Option A — .deb package (Ubuntu / Debian): the package scripts handle service registration automatically.

bash — Ubuntu / Debian

# Install — the package scripts handle everything automatically sudo dpkg -i querystreams-agent_x.x.x_amd64.deb # Fix any missing dependencies if prompted sudo apt-get install -f

Option B — .tar.gz archive (RHEL / CentOS / Fedora / any distro):

bash — RHEL / CentOS / any distro

# Extract the archive tar -xzf querystreams-agent_x.x.x_linux-x64.tar.gz # Run the install script (copies to /opt/querystreams/agent/, registers systemd service) sudo bash install.sh

Either option creates the querystreams service user, copies files to /opt/querystreams/agent/, installs and enables the querystreams-agent.service systemd unit, and starts it immediately.

Once the service is running, the local dashboard is available at http://localhost:1823 on the server (open directly, or over an SSH tunnel from your workstation). It is used to enter your authentication key and manage local data connectors. Your database credentials stay on the Agent machine and are not sent to Query Streams cloud.

Step 3: Connect the Agent to Your Account

In the local Agent dashboard at http://localhost:1823, paste your Query Streams authentication key.
Save the key and wait for the Agent to register with your organization.
Confirm the service is healthy: sudo systemctl status querystreams-agent — it should show active (running).
Select Add Data Sources to open the local connection wizard.

Step 4: Add Your First Data Source in the Local Agent

Do not add or edit connectors from the Query Streams portal. Connector setup is done in the local Network Agent dashboard at http://localhost:1823. This is where you add, edit, test, and delete database or API connectors such as PostgreSQL, MySQL, MariaDB, SQLite, Microsoft SQL Server, Oracle, Snowflake, BigQuery, DuckDB, Stripe, HubSpot, Shopify, Google Analytics 4, Google Ads, Google Search Console, ShipStation, or iTick.

Open a browser on the Linux Agent machine (or via SSH tunnel) and go to http://localhost:1823.
Click Add Data Sources or open the Agent connection area.
Choose your database or API connector type.
Enter connection details that are valid from the Linux Agent machine.
Select a data realm if prompted.
Test the connection, then save it.
For supported database connectors, leave Schema Intelligence enabled so Query Builder, Nova AI, and MCP clients get richer table and column context.

PostgreSQLHost, port, database, SSL

MySQL / MariaDBHost, port, database, SSL

SQL ServerServer, database, username, password

Local filesSQLite, DuckDB

API connectorsCredentials, sync schedule, data realm

MCP-readyAI clients can query connectors directly

Network model

# Connector management Local Agent dashboard: http://localhost:1823 # Linux Agent Runs as a systemd service, stores credentials locally, connects outbound # Your database/API Private network connection from the Agent # Query Streams cloud Receives connector metadata and routes query requests

Step 5: Build and Save Your First Query

After the connector and database are configured in the Agent, open the Query Streams portal and use Query Builder to create your first saved query. The saved query is what Excel, Google Sheets, automations, secure REST API endpoints, and shared users can run without seeing your raw SQL or database credentials.

Open Query Builder in the Query Streams portal.
Select the data connector and database that you configured in the local Agent.
Write or generate a SQL query and run a preview.
Save the query with a clear name and any filters you want users to adjust.
Run the saved query from Microsoft Excel, Google Sheets, automations, REST APIs, or shared dashboards.

Local Agent

Add, edit, test, and delete connectors at localhost:1823.

Query Builder

Select the connector, choose the database, write SQL, preview, and save.

MCP access

MCP clients can also see available connectors and query the database directly through the Agent.

Service Management Reference

bash — common management commands

# Start / stop / restart sudo systemctl start querystreams-agent sudo systemctl stop querystreams-agent sudo systemctl restart querystreams-agent # Check current status sudo systemctl status querystreams-agent # Follow live logs sudo journalctl -u querystreams-agent -f # View last 100 log lines sudo journalctl -u querystreams-agent -n 100 –no-pager

Uninstalling the Agent

The package includes an uninstall.sh script that stops the service, removes files, and optionally preserves your configuration and logs.

bash — Ubuntu / Debian (.deb uninstall)

# Remove package (keeps config files) sudo dpkg -r querystreams-agent # Full purge — also removes config, logs, and service user sudo dpkg –purge querystreams-agent

bash — tar.gz uninstall

sudo bash /opt/querystreams/agent/uninstall.sh

The uninstall script will prompt: “Keep configuration and logs? (y/N)” — enter y to preserve your appsettings.json and logs/ folder, or N to remove everything.

Troubleshooting

The Agent does not appear online +

Check service logs: sudo journalctl -u querystreams-agent -n 50 --no-pager. Common causes: incorrect authentication key entered in the local web UI at http://localhost:1823; outbound port 443 blocked by a firewall (test with curl -v https://my.querystreams.com); DNS resolution failure (nslookup my.querystreams.com).

A database connection test fails +

Test from the Linux machine where the Agent is installed. The Agent must be able to reach the database host and port directly. Also confirm the database username has read access to the tables or views you plan to query.

Do I need to open inbound firewall ports? +

No. The Agent creates an outbound encrypted connection to Query Streams. Query requests travel through that connection, so you do not expose PostgreSQL, MySQL, SQL Server, or any other database to the public internet.

Where are database credentials stored? +

Database credentials are stored in /opt/querystreams/agent/appsettings.json on the Agent machine. Query Streams cloud does not need your raw database password to route query requests through the Agent.

Where do I add, edit, or delete connectors? +

Use the Network Agent’s local dashboard at http://localhost:1823. The Query Streams portal is where you build saved queries and share access after the Agent has the connector configured.

Can I install more than one Agent? +

Yes. Each server runs an independent agent using the same organization authentication key — install on-premise, AWS EC2, Azure VMs, Google Cloud, or branch-office machines. All agents appear as separate entries in your portal, each with their own configured databases.

How do automatic updates work? +

The Agent detects whether it was installed via .deb or tar.gz and applies updates accordingly, backing up and restoring appsettings.json around the upgrade. The process runs as a detached background script — no downtime, no manual action required.

What should I do after installation? +

Create a saved query in the Query Streams portal, then run it from Microsoft Excel, Google Sheets, Nova AI, an MCP client such as Claude or Cursor, a scheduled automation, or a secure REST API endpoint.

Get Started

Install the Linux Agent and connect your first data source

Run the one-command install script, configure connectors locally at localhost:1823, then save reusable queries for Excel, Google Sheets, automations, MCP, REST APIs, and Nova AI.

Download Linux Agent

Category: Setup

Tags: Linux, Query Streams Agent, Network Agent, Setup, Database Connector, systemd

Meta Description: Install the Query Streams Agent on Linux and connect live databases securely as a systemd service.

Updated on July 2, 2026

What are your Feelings

Happy
Normal
Sad