# Connector configuration

Environment variables used by the database connector.

Source: https://docs.getaviato.com/reference/connector-configuration

These settings configure the connector process. They are separate from the API server's environment variables.

| Variable                          | Default / requirement                            | Purpose                                                                           |
| --------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
| `AVIATO_CONTROL_PLANE_URL`        | Required                                         | Absolute HTTP(S) control-plane URL.                                               |
| `AVIATO_CONNECTOR_TOKEN`          | Required                                         | Deployment credential issued for the environment.                                 |
| `AVIATO_DATABASE_URL`             | Required                                         | Main datasource connection string.                                                |
| `AVIATO_PUBLIC_URL`               | `http://localhost:8080` with the configured port | URL browsers and MCP clients use to reach the connector. Set HTTPS in production. |
| `PORT`                            | `8080`                                           | Connector listening port.                                                         |
| `AVIATO_DATA_DIR`                 | `./.aviato`                                      | Persistent local state directory; mount durable storage.                          |
| `AVIATO_DB_SCHEMA`                | `public` for PostgreSQL                          | Schema to expose.                                                                 |
| `AVIATO_MONGO_SAMPLE_SIZE`        | `1000`                                           | Documents sampled per collection for field inference.                             |
| `AVIATO_DATASOURCE_<NAME>_URL`    | Optional                                         | Additional datasource; names are lowercased. `main` and `plugin` are reserved.    |
| `AVIATO_DATASOURCE_<NAME>_SCHEMA` | `public` for PostgreSQL                          | Schema for an additional datasource.                                              |
| `AVIATO_PLUGIN_URL`               | Optional                                         | SDK plugin base URL. Requires its matching secret.                                |
| `AVIATO_PLUGIN_SECRET`            | Optional                                         | Signature secret shared with the plugin. Requires its URL.                        |
| `AVIATO_DECISIONS_URL`            | Optional                                         | Self-hosted decision service URL.                                                 |
| `AVIATO_UPLOADS_BUCKET`           | Optional                                         | Enables uploads to your S3-compatible bucket.                                     |
| `AVIATO_UPLOADS_PREFIX`           | `aviato/`                                        | Object-key prefix for uploads.                                                    |
| `AVIATO_UPLOADS_PUBLIC_URL`       | Optional                                         | Public base URL stored for uploaded files.                                        |
| `AVIATO_UPLOADS_MAX_SIZE_MB`      | `25`                                             | Per-file size limit.                                                              |

## Database connection schemes [#database-connection-schemes]

Supported connection forms include PostgreSQL (`postgres://` or `postgresql://`), MySQL (`mysql://`), MongoDB (`mongodb://` or `mongodb+srv://`), SQLite (`file:`), and libSQL (`libsql://`). MongoDB URLs must include a database name.

Use database privileges to restrict the connector independently of application roles. Protect connection strings and tokens as secrets.

The implementation of this reference is [runtime/config.ts](https://github.com/getaviato/aviato/blob/master/packages/connector-core/src/runtime/config.ts).

## Upgrading from the agent name [#upgrading-from-the-agent-name]

The customer-side runtime is now **Aviato Connector**. AI agents remain MCP clients of the connector.

* Deploy the updated control plane before upgrading connectors or the dashboard. New connectors call `/connector/v1`; the control plane also accepts `/agent/v1` for existing binaries.
* Use `AVIATO_CONNECTOR_TOKEN`. `AVIATO_AGENT_TOKEN` remains accepted; a nonblank new variable takes precedence.
* Use `CONNECTOR_HOSTING` and `CONNECTOR_IMAGE` on the control plane. Their `AGENT_` aliases remain accepted. `NOTES_CONNECTOR_PRIVATE_ORIGINS` replaces `NOTES_AGENT_PRIVATE_ORIGINS` with the same fallback.
* Use `aviato-connector` and `aviato/connector`. Release packaging retains the old binary asset names, executable path in Docker, and image tags. These aliases become available only when a connector release is published; this source change does not publish binaries or images.
* Laravel accepts existing `aviato.agent` configuration and `AVIATO_AGENT_*` variables. Existing published configuration takes precedence over package defaults; move that section to `aviato.connector` when updating it. `--agent-version` remains an alias for `--connector-version`. Go retains `cmd/aviato-agent-install` alongside `cmd/aviato-connector-install`.
* Existing database tables, Docker container and volume identities, JWT audiences, protobuf wire fields and `agent.status` events retain their original names. No data migration or credential rotation is required.
* Dashboard GraphQL fields use `connectorSession`, `connectorStatus`, `connectorUrl`, `connectorConnectedAt`, `connectorCredential`, `hostedConnectorsAvailable` and `rotateConnectorCredential`. The old fields remain as deprecated aliases. Existing `AgentSession` and `AgentStatus` fragment type names remain compatible.

Keep the connector's data directory when replacing its process or container. It holds queued audit events and local state. Public binary availability still needs separate release verification; use a supplied binary or build from source until it is verified.