Aviato / docs
Reference

Connector configuration

Environment variables used by the database connector.

View Markdown

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

VariableDefault / requirementPurpose
AVIATO_CONTROL_PLANE_URLRequiredAbsolute HTTP(S) control-plane URL.
AVIATO_CONNECTOR_TOKENRequiredDeployment credential issued for the environment.
AVIATO_DATABASE_URLRequiredMain datasource connection string.
AVIATO_PUBLIC_URLDetected from the platform, else http://localhost:<port>URL browsers and MCP clients use to reach the connector; takes precedence over detection. A blank value is read as missing, and the connector warns at startup when the URL it advertises is a loopback address.
PORT8080Connector listening port.
AVIATO_DATA_DIR./.aviato, /var/lib/aviato in the imagePersistent local state directory; mount durable storage. Checked at startup.
AVIATO_RUN_UID65532 when started as rootUser the connector continues as after preparing the data directory. 0 keeps root. Ignored when the container already runs as another user.
AVIATO_RUN_GIDThe configured userGroup that goes with AVIATO_RUN_UID.
AVIATO_DB_SCHEMApublic for PostgreSQLSchema to expose.
AVIATO_MONGO_SAMPLE_SIZE1000Documents sampled per collection for field inference.
AVIATO_DATASOURCE_<NAME>_URLOptionalAdditional datasource; names are lowercased. main and plugin are reserved.
AVIATO_DATASOURCE_<NAME>_SCHEMApublic for PostgreSQLSchema for an additional datasource.
AVIATO_PLUGIN_URLOptionalSDK plugin base URL. Requires its matching secret.
AVIATO_PLUGIN_SECRETOptionalSignature secret shared with the plugin. Requires its URL.
AVIATO_DECISIONS_URLOptionalSelf-hosted decision service URL.
AVIATO_UPLOADS_BUCKETOptionalEnables uploads to your S3-compatible bucket.
AVIATO_UPLOADS_PREFIXaviato/Object-key prefix for uploads.
AVIATO_UPLOADS_PUBLIC_URLOptionalPublic base URL stored for uploaded files.
AVIATO_UPLOADS_MAX_SIZE_MB25Per-file size limit.

Commands

CommandPurpose
aviato start (or aviato alone)Runs the connector with the variables above. SIGHUP reloads the plugin manifest and re-introspects the database.
aviato devRuns the connector for local plugin development: loads aviato.env when present, reloads the plugin manifest every second, and waits for the plugin to start. --types keeps generated files up to date. --project <id> (or AVIATO_PROJECT without a connector token) runs your own development environment of the project, approved once in the browser; --login approves again and --no-open only prints the approval link. --tunnel shares the connector through a temporary Cloudflare quick tunnel and advertises its address, offering to install cloudflared when it is missing.
aviato initAsks for the connection settings, checks them, and writes aviato.env.
aviato typegen --out <path>Generates collection and field names for TypeScript, Go or PHP plugin code from the databases. Needs only the database variables. --check fails when the output is out of date.
aviato snapshotWrites the introspected schema and, when AVIATO_PLUGIN_URL is set, the plugin manifest as JSON (--output for a file). --schema and --manifest read them from files.
aviato diff --base <file>Compares a snapshot with --head (or a fresh snapshot) and lists additions, changes and breaking changes. --format text|markdown|json; --fail-on-breaking exits with status 1 on a breaking change.
aviato auditLists rejected audit events, or replays them once their cause is fixed.
aviato preview up --name <name>Opens a preview environment for CI, or extends it, and prints the connector's variables. preview down --name <name> closes it. Reads AVIATO_PREVIEW_KEY and AVIATO_CONTROL_PLANE_URL. See Preview environments.

See Typed plugins and local development for dev, typegen, snapshot and diff.

Container image

The connector image is published on Docker Hub as getaviato/connector, built for linux/amd64 and linux/arm64 from the binaries of the same release. Tags are the connector version (0.5.2) plus latest for the newest stable release; pin a version. The image sets PORT=8080 and AVIATO_DATA_DIR=/var/lib/aviato, and declares that path as a volume. Its entrypoint is /usr/local/bin/aviato, with aviato-connector and aviato-agent kept as symlinks to it.

It starts as root, gives the data directory to uid 65532 and continues as that user, before it contacts the control plane, connects to a database or opens a file: a volume that Railway, Fly or a Kubernetes PVC mounts as root is writable without preparation, and no request is ever served as root. Set AVIATO_RUN_UID, or run the container with a user (docker run --user, a securityContext), to decide this yourself; the connector keeps the user it is given and the mount then has to belong to it. On a mount that refuses to change owner — read-only, NFS, SMB — the connector warns and keeps the privileges that can write it.

See running the connector for Docker and Railway deployments.

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.

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 the aviato CLI and the getaviato/connector image. Release assets are published under the aviato-* names only; the image keeps the aviato-connector and aviato-agent executable paths as aliases of aviato. There are no aviato/agent image tags: the aviato Docker Hub namespace is an unrelated account, and no connector image was ever published under the agent name, so nothing can depend on it.
  • 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. Binaries and the image of each release are published from the same build: the binaries in the public getaviato/connector repository (see Install the CLI), the image on Docker Hub.

Edit on GitHub

On this page