Running a local agent

What is the local agent?

The nuzur local agent is a small daemon you run on your own machine. It creates a secure tunnel between your local 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 your machine.

Your DSN never leaves your computer. 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 local MySQL or PostgreSQL database

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 local 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

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