Connector configuration
Environment variables used by the database connector.
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 | Detected 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. |
PORT | 8080 | Connector listening port. |
AVIATO_DATA_DIR | ./.aviato, /var/lib/aviato in the image | Persistent local state directory; mount durable storage. Checked at startup. |
AVIATO_RUN_UID | 65532 when started as root | User the connector continues as after preparing the data directory. 0 keeps root. Ignored when the container already runs as another user. |
AVIATO_RUN_GID | The configured user | Group that goes with AVIATO_RUN_UID. |
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. |
Commands
| Command | Purpose |
|---|---|
aviato start (or aviato alone) | Runs the connector with the variables above. SIGHUP reloads the plugin manifest and re-introspects the database. |
aviato dev | Runs 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 init | Asks 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 snapshot | Writes 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 audit | Lists 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/v1for existing binaries. - Use
AVIATO_CONNECTOR_TOKEN.AVIATO_AGENT_TOKENremains accepted; a nonblank new variable takes precedence. - Use
CONNECTOR_HOSTINGandCONNECTOR_IMAGEon the control plane. TheirAGENT_aliases remain accepted.NOTES_CONNECTOR_PRIVATE_ORIGINSreplacesNOTES_AGENT_PRIVATE_ORIGINSwith the same fallback. - Use the
aviatoCLI and thegetaviato/connectorimage. Release assets are published under theaviato-*names only; the image keeps theaviato-connectorandaviato-agentexecutable paths as aliases ofaviato. There are noaviato/agentimage tags: theaviatoDocker 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.agentconfiguration andAVIATO_AGENT_*variables. Existing published configuration takes precedence over package defaults; move that section toaviato.connectorwhen updating it.--agent-versionremains an alias for--connector-version. Go retainscmd/aviato-agent-installalongsidecmd/aviato-connector-install. - Existing database tables, Docker container and volume identities, JWT audiences, protobuf wire fields and
agent.statusevents retain their original names. No data migration or credential rotation is required. - Dashboard GraphQL fields use
connectorSession,connectorStatus,connectorUrl,connectorConnectedAt,connectorCredential,hostedConnectorsAvailableandrotateConnectorCredential. The old fields remain as deprecated aliases. ExistingAgentSessionandAgentStatusfragment 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.