Aviato / docs
Plugins & integrations

Run the database connector

Connect a self-hosted connector to your project and database, with Docker, Railway or the binary.

View Markdown

Create the connection

Create a self-hosted project in the dashboard. Copy its connector token and control-plane URL. Use a database account with only the privileges you intend Aviato to expose.

The project's setup instructions show the same commands as this guide, with your control-plane URL and token already filled in.

Run it with Docker

The connector image is published on Docker Hub as getaviato/connector, for linux/amd64 and linux/arm64. Pin the version you deploy instead of latest:

docker run -d --name aviato-connector \
  -e AVIATO_CONTROL_PLANE_URL=https://api.getaviato.com \
  -e AVIATO_CONNECTOR_TOKEN=replace-with-the-token-from-your-project \
  -e AVIATO_DATABASE_URL=postgres://aviato:[email protected]:5432/app \
  -p 8080:8080 \
  -v aviato-data:/var/lib/aviato \
  getaviato/connector:0.5.2

The image listens on port 8080 and keeps its state in /var/lib/aviato. Keep that volume across upgrades; it holds the audit outbox and local registries. Use --env-file aviato.env instead of repeated -e flags to keep secrets out of your shell history.

Add -e AVIATO_PUBLIC_URL=https://connector.example.com when the connector is reached through your own domain or proxy. On a platform that publishes a domain for the service, the connector reads it and needs no setting at all.

The image starts as root, hands /var/lib/aviato to its service user (uid 65532) and continues as that user, so a volume the platform mounts as root is writable without preparation. Pin a user with --user or AVIATO_RUN_UID to decide this yourself; the connector then keeps the user it is given.

Run it on Railway

Declare the connector as a Railway service in .railway/railway.ts and apply it with railway config apply:

import { defineRailway, image, project, service, volume } from "railway/iac";

export default defineRailway(() => {
    // Keeps the audit outbox, cache and upload registry across redeploys.
    const connectorData = volume("aviato-connector-data", { sizeMB: 1024 });

    // Generate a domain for the service: the connector advertises RAILWAY_PUBLIC_DOMAIN to the dashboard.
    const connector = service("aviato-connector", {
        source: image("getaviato/connector:0.5.2"),
        healthcheck: "/v1/health",
        replicas: 1,
        volumeMounts: { "/var/lib/aviato": connectorData },
        env: {
            AVIATO_CONTROL_PLANE_URL: "https://api.getaviato.com",
            AVIATO_CONNECTOR_TOKEN: "<your connector credential>",
            AVIATO_DATABASE_URL: "<your db url>",
        },
    });

    return project("aviato", { resources: [connector, connectorData] });
});

Two things belong to Railway rather than to the connector:

  • The volume. Railway filesystems are ephemeral and the audit outbox lives in the data directory. Railway mounts it as root; the image takes it over at startup, so there is nothing to set.
  • A single replica. The upload and record registries are local to one data directory, and Railway does not combine replicas with a volume.

Generate a domain for the service. The connector reads RAILWAY_PUBLIC_DOMAIN and advertises it, so AVIATO_PUBLIC_URL is only needed for a custom domain.

Install the CLI

The connector also ships as a single executable, the aviato CLI, for macOS (Apple silicon and Intel), Linux (x64 and arm64) and Windows (x64). It is the same program as the image, and the CLI you use for development environments, typed plugins and previews.

# macOS and Linux
curl -fsSL https://getaviato.com/install.sh | sh

# Homebrew
brew install getaviato/tap/aviato

# Windows (PowerShell)
irm https://getaviato.com/install.ps1 | iex

The install script downloads the binary for your system from the latest release, checks it against the release's checksums.txt, and installs it in ~/.local/bin (%LOCALAPPDATA%\aviato\bin on Windows, added to your PATH). It needs no administrator rights. Set AVIATO_VERSION=0.5.1 to install a given release, or AVIATO_INSTALL_DIR to choose the directory. Run it again to upgrade; with Homebrew, run brew upgrade aviato. Check the installed version with aviato --version.

The x64 builds need a processor with AVX2 (Intel since 2013, AMD since 2015).

Run the binary

Pin the release you deploy on a server. The examples below assume aviato is on your PATH.

Run the setup wizard, which checks the token and the database connection:

aviato init

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

AVIATO_CONTROL_PLANE_URL=https://api.getaviato.com
AVIATO_CONNECTOR_TOKEN=replace-with-the-token-from-your-project
AVIATO_DATABASE_URL=postgres://aviato:[email protected]:5432/app
AVIATO_PUBLIC_URL=https://connector.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 for additional databases and plugin settings.

chmod 600 aviato.env
set -a
. ./aviato.env
set +a
aviato start

For plugin development on your machine, aviato dev reloads the plugin manifest every second and waits for a plugin that is still starting. With --project, it runs your own development environment of the project, without a token to copy, and --tunnel gives it a temporary public address for MCP clients. aviato typegen generates collection and field names for plugin code. See Typed plugins and local development.

Make it reachable

Your team's browsers and MCP clients connect to the connector directly, so the address it advertises has to be the one they use: a URL that only the control plane can reach is not sufficient.

The connector finds that address by itself where the platform publishes one — RAILWAY_PUBLIC_DOMAIN, RENDER_EXTERNAL_URL, FLY_APP_NAME. Set AVIATO_PUBLIC_URL when you run it anywhere else, or behind your own domain, and place an HTTPS reverse proxy in front of port 8080; it takes precedence over anything detected.

With neither, the connector advertises http://localhost:<port>, which reaches nothing from a teammate's laptop, and logs a warning at startup saying so. It keeps running: a connector reached over a private network or a tunnel is a legitimate setup. For a development environment, aviato dev --tunnel opens a tunnel and sets the address for you. The control plane stores the connector's reported URL on every heartbeat, so correcting the address and restarting is enough to recover.

Persist the connector's state

Mount AVIATO_DATA_DIR on durable storage (/var/lib/aviato in the image, ./.aviato otherwise). It holds the audit outbox, approval recovery state, the upload ownership registry, and caches. The image makes a root-owned mount writable itself; a mount that cannot be written at all, or one pinned to another user, stops the connector at startup with an explicit message. Give each replica its own data directory; do not share a SQLite-backed directory between running replicas, and route a browser's upload, write and download requests to the same replica.

Verify the connection

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

The connector needs outbound access to the control plane, audit ingestion, its configured databases, and any SDK plugin. Read troubleshooting if it does not connect.

Edit on GitHub

On this page