# Run the database agent (https://docs.getaviato.com/integrations/agent)



## Create the connection [#create-the-connection]

Create a self-hosted project in the [dashboard](https://app.getaviato.com). Copy its agent token and control-plane URL. Use a database account with only the privileges you intend Aviato to expose.

Install the agent binary for your platform from the project's setup instructions or the [agent releases](https://github.com/getaviato/aviato/releases). Pin the release you deploy. The examples below assume `aviato-agent` is on your PATH.

## Configure it [#configure-it]

Run the setup wizard:

```bash
aviato-agent init
```

Or create an `aviato.env` file and restrict who can read it:

```dotenv
AVIATO_CONTROL_PLANE_URL=https://api.getaviato.com
AVIATO_AGENT_TOKEN=replace-with-the-token-from-your-project
AVIATO_DATABASE_URL=postgres://aviato:password@database.internal:5432/app
AVIATO_PUBLIC_URL=https://agent.example.com
AVIATO_DATA_DIR=/var/lib/aviato
PORT=8080
```

Use your own URLs and credentials. Keep this file out of source control. See the [configuration reference](/reference/agent-configuration) for additional databases and plugin settings.

## Run it [#run-it]

```bash
chmod 600 aviato.env
set -a
. ./aviato.env
set +a
aviato-agent
```

Place an HTTPS reverse proxy in front of port 8080. The public URL must be reachable from your users' browsers and MCP clients; a URL that only the control plane can reach is not sufficient.

## Persist the agent's state [#persist-the-agents-state]

Mount `AVIATO_DATA_DIR` on durable storage. It holds the audit outbox, approval recovery state, and caches. Give each replica its own data directory; do not share a SQLite-backed directory between running replicas.

## Verify the connection [#verify-the-connection]

Request `GET /v1/health` on the agent, then open the project in the dashboard. Confirm its status, environment, and discovered collections. Try a read before enabling writes.

The agent needs outbound access to the control plane, audit ingestion, its configured databases, and any SDK plugin. Read [troubleshooting](/administration/troubleshooting) if it does not connect.