@vaultgradient/pq-agent

The agent that runs inside your network so AI agents can query your data — safely, audibly, and over a single outbound connection.

pq-agent is half of PipeQuery Cloud. The other half is the hosted control plane your AI tools (Claude Desktop, Cursor, Copilot, custom MCP clients) connect to. The agent sits between them and your data sources, so:

• Your data stays on your infra. Source credentials live in your pipequery.yaml. The control plane never sees them.
• No inbound ports. The agent dials out to the control plane over WSS:443. Your firewall stays closed.
• Every read is audited. Each query produces a tamper-evident audit entry persisted in the control plane.

Install

npm install -g @vaultgradient/pq-agent

Requires Node 24 or later (inherited from @vaultgradient/pipequery-cli).

Configure

Create a pipequery.yaml next to your data:

sources:
  orders:
    type: postgres
    url: ${DATABASE_URL}
    query: SELECT * FROM orders
    interval: 30s

endpoints:
  /top-orders:
    query: orders | sort(total desc) | first(10)

pq-agent reuses the PipeQuery source library: Postgres, MySQL, SQLite, Snowflake, ClickHouse, MongoDB, Kafka, REST APIs, WebSocket streams, CSV / JSON files, inline data. Connection strings support ${ENV_VAR} interpolation so secrets stay out of yaml.

Run

You need two things from your control-plane operator (or your own pq-cloud-admin if you self-host):

1. Control-plane URL — e.g. wss://pipequery-cloud.fly.dev/agent
2. Agent token — issued via pq-cloud-admin issue-agent-token. The token is shown once.

Then:

export PQ_AGENT_CONTROL_PLANE_URL=wss://your-cp.fly.dev/agent
export PQ_AGENT_ENROLLMENT_TOKEN=<your-agent-token>
export PQ_AGENT_CONFIG=./pipequery.yaml

pq-agent run

You should see:

[agent] loading config from /path/to/pipequery.yaml
[agent] loaded 1 source(s), 1 endpoint(s)
[agent] connected to wss://your-cp.fly.dev/agent (auth=enrollment)

The agent now serves MCP traffic from the control plane against your sources. Your AI client uses the MCP URL (e.g. https://your-cp.fly.dev/mcp) plus an api_key — issued separately, also via the admin CLI.

As a service (systemd / launchd)

For production, run pq-agent under a process supervisor. Example systemd unit:

[Unit]
Description=PipeQuery agent
After=network.target

[Service]
Environment=PQ_AGENT_CONTROL_PLANE_URL=wss://your-cp.fly.dev/agent
Environment=PQ_AGENT_ENROLLMENT_TOKEN=...
Environment=PQ_AGENT_CONFIG=/etc/pipequery/pipequery.yaml
ExecStart=/usr/bin/pq-agent run
Restart=on-failure
User=pipequery

[Install]
WantedBy=multi-user.target

How it works

┌─────────────────────┐         ┌──────────────────────────┐
│   Claude Desktop    │ HTTPS   │   PipeQuery Cloud        │
│   Cursor / Copilot  │ ──────► │   <your-cp>.fly.dev/mcp  │
│   (any MCP client)  │         │                          │
└─────────────────────┘         │   ┌────────────────────┐ │
                                │   │ Tenant registry    │ │
                                │   │ Audit log (Postgres)│ │
                                │   └────────────────────┘ │
                                │             │            │
                                │             │ WSS (long-lived)
                                │             ▼            │
                                └─────────────┬────────────┘
                                              │
                                  outbound :443 only
                                              │
                                              ▼
                                ┌──────────────────────────┐
                                │  pq-agent (this package) │
                                │  Inside YOUR network     │
                                │                          │
                                │  ┌────────────────────┐  │
                                │  │ pipequery.yaml     │  │
                                │  │ source credentials │  │
                                │  └────────────────────┘  │
                                │             │            │
                                │             ▼            │
                                │   Postgres / Snowflake /  │
                                │   Kafka / REST APIs / etc │
                                └──────────────────────────┘

The agent dials the control plane over WSS:443. When the AI client makes an MCP tool call, the control plane routes it through the WS to the agent, the agent executes the query locally using whichever source adapter is configured (with push-down to native SQL where supported), and the result streams back. Source credentials never cross the public internet — only the query results do.

CLI reference

pq-agent run [options]

Options:
  --url <url>           Control-plane WSS URL
                        (env: PQ_AGENT_CONTROL_PLANE_URL)
  --config <path>       Path to pipequery.yaml
                        (env: PQ_AGENT_CONFIG, default: ./pipequery.yaml)
  --token-file <path>   Where to read/write the agent token
                        (env: PQ_AGENT_TOKEN_FILE,
                         default: $XDG_DATA_HOME/pipequery/agent.token)
  --insecure            Allow ws:// for localhost-only dev. Refused
                        against any non-localhost host.

Troubleshooting

• Refusing to connect: URL must use wss:// — the production control plane uses TLS; ws:// is allowed only for localhost dev.
• WS closed 4001 — your agent token is invalid or revoked. Get a fresh one from your operator (pq-cloud-admin issue-agent-token).
• WS closed 4003 — protocol version mismatch. Upgrade pq-agent to the latest.
• AUDIT CHAIN BREAK in the CP logs after a restart — known v1 limitation: the agent's chain resets to zero on restart. Fix is on the roadmap (disk-persistence of the chain head).

License

Proprietary. © Vault Gradient. Commercial licensing inquiries: pipequery.cloud.