---
title: 'Running a local agent'
group: 'data-manager'
---

## 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](https://nuzur.com/cli))
- A nuzur account with a **Pro or Enterprise** plan
- A local MySQL or PostgreSQL database

---

## Step 1 — Install the CLI

Download and install the nuzur CLI from [nuzur.com/cli](https://nuzur.com/cli), then verify the installation:

```bash
nuzur-cli --version
```

---

## Step 2 — Log in

```bash
nuzur-cli login
```

This opens your browser for authentication. Once complete, your credentials are saved locally and reused automatically.

---

## Step 3 — Pair this machine

Registering your machine creates a local agent entry in your nuzur account:

```bash
nuzur-cli agent pair
```

On success you will see the agent's UUID and the path where credentials are stored:

```
Paired local agent.
  uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  machine: my-laptop (darwin)
  credentials stored at: ~/.config/nuzur/agent/
```

To see all paired agents on your account:

```bash
nuzur-cli agent list
```

---

## Step 4 — Register a database connection

```bash
nuzur-cli agent connection add
```

The CLI will prompt 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.

To see all registered connections:

```bash
nuzur-cli agent connection list
```

To remove a connection:

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

---

## Step 5 — Start the agent

```bash
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

| Flag | Description |
|---|---|
| `--driver` | Database driver (`mysql` or `postgres`) |
| `--dsn` | Full DSN string (skips the interactive prompt) |
| `--reset-db` | Discard saved DSN/driver and re-prompt |
| `--max-concurrent-queries` | Cap simultaneous DB queries (default: 32) |

Environment variables `NUZUR_AGENT_DRIVER` and `NUZUR_AGENT_DSN` are also accepted.

---

## Step 6 — Auto-start at login (optional)

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

```bash
nuzur-cli agent install
```

Supported on **macOS** (launchd) and **Linux** (systemd user service).

To stop and remove the service:

```bash
nuzur-cli agent uninstall
```

---

## Checking status

```bash
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:

```bash
nuzur-cli agent self-test
```

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

---

## Unpairing a machine

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

```bash
nuzur-cli agent unpair
```

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

```bash
nuzur-cli agent unpair --keep-remote
```

---

## Next steps

- [Data Manager overview](/docs/data-manager-overview)
- [Connecting to databases](/docs/data-manager-connect)
- [Managing data](/docs/data-manager-manage-data)