Running a local agent

What is the local agent?

The nuzur local agent is a small daemon you run wherever your database lives — your own computer during development, or a server (VPS) hosting a self-hosted database in production. It creates a secure tunnel between that database and the nuzur Data Manager — so you can browse, query, and manage data in nuzur without exposing your database to the internet or storing credentials anywhere outside the machine.

Your DSN never leaves the machine the agent runs on. Only query results are forwarded through the encrypted tunnel.

Requirements

• nuzur CLI installed (download)
• A nuzur account (the Starter free plan includes 1 database connection; Pro and Team plans have unlimited connections)
• A MySQL or PostgreSQL database on the machine where the agent runs (your computer or a server/VPS)

Step 1 — Install the CLI

Download and install the nuzur CLI from nuzur.com/cli, then verify the installation:

nuzur-cli --version

Step 2 — Add a database connection

nuzur-cli agent connection add

The first time you run this, the CLI logs you in (opening your browser) and pairs this machine automatically — there's no separate login or agent pair step. It then prompts you for:

• Name — a label for this connection (e.g. local-mysql)
• Driver — mysql or postgres
• Host / Port / User / Password — your database credentials
• Database (Postgres only) — the target database name
• Default schema (Postgres only) — typically public

Connection metadata (name, driver, schema) is published to nuzur. Your DSN stays on disk, never on the cloud.

Plan limit: the Starter free plan allows a single database connection. Pro and Team plans have unlimited connections.

To see all registered connections:

nuzur-cli agent connection list

To remove a connection:

nuzur-cli agent connection remove <name-or-uuid>

Step 3 — Start the agent

nuzur-cli agent start

The agent runs in the foreground and waits for incoming query requests from nuzur. Leave this terminal open while using the Data Manager.

Stop it at any time with Ctrl+C.

Options

Environment variables NUZUR_AGENT_DRIVER and NUZUR_AGENT_DSN are also accepted.

Step 4 — Auto-start at login (optional)

To have the agent start automatically when you log in, install it as an OS-managed service:

nuzur-cli agent install

Supported on macOS (launchd) and Linux (systemd user service). On Windows, run nuzur-cli agent start manually for now — managed auto-start is not yet available.

To stop and remove the service:

nuzur-cli agent uninstall

Checking status

nuzur-cli agent status

Shows pairing state, saved DSN/driver, and whether the auto-start service is installed.

Verifying the connection

With the agent running in a terminal, run the self-test in another shell:

nuzur-cli agent self-test

This sends a SELECT 1 through the full cloud → agent → database round-trip and prints OK on success.

Managing paired machines

Pairing happens automatically the first time you add a connection, so you rarely need to do it by hand. If you want to pair a machine ahead of time (for example, to provision it before adding connections), run:

nuzur-cli agent pair

On a headless server (VPS) where opening a browser isn't practical, pair with a short-lived provisioning token instead:

nuzur-cli agent pair --provisioning-token <token>

This is what nuzur-cli deploy uses under the hood to pair deployed servers automatically.

To list every machine paired to your account:

nuzur-cli agent list

Unpairing a machine

To revoke this machine's agent from the cloud and remove local credentials:

nuzur-cli agent unpair

If the cloud row was already removed elsewhere, use --keep-remote to wipe only the local files:

nuzur-cli agent unpair --keep-remote

Next steps

• Data Manager overview
• Connecting to databases
• Managing data