View Categories

How to Install the Query Streams Agent on macOS

9 min read

macOS logo macOS Network Agent

Install Query Streams on macOS

Run the outbound-only Query Streams Network Agent on macOS 12 Monterey or later. One install script registers it as a system-level launchd daemon — native builds for Apple Silicon (M1–M4) and Intel. 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 launchd service
Terminal — zsh
%tar -xzf querystreams-agent_x.x.x_osx-arm64.tar.gz
%sudo bash install.sh|
>[4/4] Service is running.
>Web UI: http://localhost:1823
com.querystreams.agent running
Installing on a different OS?
Windows Windows Linux Linux
See everything Query Streams can do after the macOS Agent is online Get Started Free
Connectors
SQL Server PostgreSQL MySQL MariaDB SQLite Microsoft Access Oracle BigQuery DuckDB
+ APIs
Microsoft Excel Google Sheets
Live Data

Run saved SQL directly from spreadsheets

Excel Sheets
Nova AI
BI & AI Analytics

Ask Nova questions over connected data

Meet Nova
REST API
Database REST API

Turn saved queries into secure endpoints

Build an API
Airtable Smartsheet Baserow +more
Automation

Schedule syncs and push live results

Explore
Stripe HubSpot Shopify Google Analytics +more
API to SQL

Query SaaS APIs with SQL

Explore
MCP Claude Cursor ChatGPT
AI Database MCP

Let AI tools query connectors directly

Connect AI

Query Streams is a secure, real-time data access platform that lets Mac users and development teams connect live databases to 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 macOS Agent.

This guide covers installing the Agent on macOS. The package includes a one-command install script that copies files to /usr/local/querystreams/agent/ and registers a system-level launchd daemon — available as native ARM64 (Apple Silicon M1–M4) and native x64 (Intel) builds. 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 macOS versions

macOS 12 Monterey or later (Monterey, Ventura, Sonoma, Sequoia). Both Apple Silicon and Intel supported with native binaries.

Admin / sudo access

Required. The install script runs as root to install to /usr/local/ and register the system LaunchDaemon.

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 Mac that is on the same network, VPN, or routable environment as your database or API source.

Step 1: Download the macOS Agent

1
2
3
4
5
  1. Sign in to my.querystreams.com/download.
  2. Choose macOS from the Agent download options.
  3. Choose ARM64 (Apple Silicon — check Apple menu > About This Mac: if it shows “Apple M1/M2/M3/M4”, use this) or x64 (Intel Core) and download the .tar.gz archive.
  4. Copy your organization authentication key from the same download page. You will use it when the local Agent dashboard opens.

Step 2: Run the Install Script

2
3
4
5

Open Terminal (Applications > Utilities > Terminal) and run:

Terminal — zsh
# Extract the archive tar -xzf querystreams-agent_x.x.x_osx-arm64.tar.gz # Optional (signed & notarized, usually not needed): clear quarantine, then run the install script xattr -dr com.apple.quarantine . sudo bash install.sh

The install.sh script performs four steps automatically: copies files to /usr/local/querystreams/agent/, sets correct permissions, installs the launchd plist to /Library/LaunchDaemons/com.querystreams.agent.plist as a system-wide daemon, and loads the service via launchctl load — starting it immediately and on every boot.

Signed & Notarized: the Query Streams macOS Agent is code-signed and notarized by Apple, so it runs normally under Gatekeeper — no extra steps needed for most users. In the rare case a first-run prompt appears (for example, if the archive was copied between machines after quarantine flags were reapplied), clear the quarantine attribute with xattr -dr com.apple.quarantine qs-agent/ and re-run sudo bash install.sh.

Once the service is running, the local dashboard is available at http://localhost:1823 on the Mac. 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

3
4
5
  1. In the local Agent dashboard at http://localhost:1823, paste your Query Streams authentication key.
  2. Save the key and wait for the Agent to register with your organization.
  3. Confirm the service is healthy: sudo launchctl list | grep querystreams.
  4. Select Add Data Sources to open the local connection wizard.

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

4
5

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.

  1. Open a browser on the macOS Agent machine and go to http://localhost:1823.
  2. Click Add Data Sources or open the Agent connection area.
  3. Choose your database or API connector type.
  4. Enter connection details that are valid from the macOS Agent machine.
  5. Select a data realm if prompted.
  6. Test the connection, then save it.
  7. For supported database connectors, leave Schema Intelligence enabled so Query Builder, Nova AI, and MCP clients get richer table and column context.
PostgreSQL
PostgreSQLHost, port, database, SSL
MySQL
MySQL / MariaDBHost, port, database, SSL
SQL Server
SQL ServerServer, database, username, password
DuckDB
Local filesSQLite, DuckDB
Stripe
API connectorsCredentials, sync schedule, data realm
MCP
MCP-readyAI clients can query connectors directly
Network model
# Connector management Local Agent dashboard: http://localhost:1823 # macOS Agent Runs as a launchd daemon, 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

5

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.

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

Local Agent

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

2

Query Builder

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

3

User tools

Saved queries become available in Excel, Google Sheets, automations, and APIs.

4

MCP access

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

Service Management Reference

Terminal — launchd management
# Stop the service sudo launchctl unload /Library/LaunchDaemons/com.querystreams.agent.plist # Start the service sudo launchctl load /Library/LaunchDaemons/com.querystreams.agent.plist # Check running status sudo launchctl list | grep querystreams # View live logs tail -f /usr/local/querystreams/agent/logs/agent-stdout.log # View error log tail -f /usr/local/querystreams/agent/logs/agent-stderr.log

Uninstalling the Agent

The package includes an uninstall.sh script that stops and unloads the launchd service, removes the plist from /Library/LaunchDaemons/, and removes the installation directory.

Terminal — uninstall
sudo bash /usr/local/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

macOS says “cannot be opened because the developer cannot be verified” +
Remove the Gatekeeper quarantine attribute from the extracted folder before running the install script: xattr -dr com.apple.quarantine qs-agent/, then re-run sudo bash install.sh. Alternatively, go to System Settings > Privacy & Security and click “Allow Anyway” after the first blocked attempt.
The Agent does not appear online +
Check logs: tail -50 /usr/local/querystreams/agent/logs/agent-stdout.log. Common causes: incorrect authentication key entered in the local web UI at http://localhost:1823; outbound port 443 blocked by a proxy (test with curl -v https://my.querystreams.com); Gatekeeper still blocking (confirm the quarantine attribute was removed before install).
A database connection test fails +
Test from the Mac 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.
Should I use ARM64 or x64? +
Go to Apple menu > About This Mac. If the chip shows “Apple M1/M2/M3/M4”, use ARM64. If it shows “Intel Core”, use x64. Using the wrong build still works via Rosetta 2, but the matching native build is always preferred.
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. No macOS Firewall changes are required.
Where are database credentials stored? +
Database credentials are stored in /usr/local/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.
How do automatic updates work on macOS? +
The Agent checks the portal for new releases matching your platform (osx-arm64 or osx-x64). When available, it unloads the launchd plist, backs up appsettings.json, extracts the new binary, restores the config, and reloads the service — fully automatic, no user action required.

Get Started

Install the macOS 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 macOS Agent

Related guides: Install the Query Streams Agent on Windows | Install the Query Streams Agent on Linux | Install the Query Streams Google Sheets Add-on | Use Query Streams with Microsoft Excel

Category: Setup

Tags: macOS, Query Streams Agent, Network Agent, Setup, Database Connector, launchd

Meta Description: Install the Query Streams Agent on macOS and connect live databases securely as a launchd daemon.

Updated on July 2, 2026

What are your Feelings

  • Happy
  • Normal
  • Sad

Powered by BetterDocs