Installation — Vercel

ARI can be installed on your own macOS, Windows or Linux computer, or hosted on the cloud. ARI runs beautifully on Vercel. Press Deploy with Vercel and you'll have your own private ARI workspace, live on the internet, in minutes. Vercel hosts it, keeps it fast for you anywhere in the world, and automatically ships every future update the moment you make it.

Step 1 — Create a Vercel Account

Please create a free account on Vercel.com. If you already have one, just sign in.

Step 2 — Deploy

Once you are signed into Vercel, click the deploy button below:

1. Vercel asks you to create a Git repository (GitHub, GitLab, or Bitbucket) — this is your copy of ARI, which Vercel redeploys on every push.
2. Vercel creates the project and runs the first build. No environment variables are required at this stage.
3. When the build finishes, open the deployment URL. You will land on the ARI setup wizard.

Step 3 — Set Up a Database

ARI needs a PostgreSQL database. Vercel does not provide one, so create a free hosted database with either provider below and copy its connection string into the wizard.

1. Neon (simplest)

   Create a project at neon.tech, then copy the connection string from the project dashboard. Neon's pooled connection string works with Vercel out of the box.

2. Supabase

   Create a project at supabase.com. Then open Connect (top of the dashboard) and choose the connection string carefully:

   • Select the Transaction pooler connection method — not "Direct connection." Vercel runs ARI as serverless functions, and the transaction pooler is built for exactly that (short, isolated requests) while multiplexing connections so your database is not overwhelmed.
   • The transaction pooler is IPv4-compatible, which is what you need on Vercel. The Direct connection option is IPv6-only by default — Vercel's functions cannot reach it without Supabase's paid IPv4 add-on, so it will fail to connect. Always use the pooler string.
   • Set Type to URI and copy the string. It looks like postgresql://postgres.your-project-ref:[YOUR-PASSWORD]@aws-0-region.pooler.supabase.com:6543/postgres — note port 6543 and the postgres.<ref> username, which distinguish the pooler from the direct string.
   • Replace [YOUR-PASSWORD] with your database password. If the password contains special characters, percent-encode them.

ARI tests the connection before saving anything, so a wrong string fails fast with a clear message rather than a broken deployment.

Step 4 — Create a Vercel Access Token

ARI uses a Vercel access token once — to write your configuration to the project's environment variables and trigger the redeploy. It is never stored, logged, or shown again.

1. Go to vercel.com/account/tokens.
2. Create a token with access to the account or team that owns this deployment.
3. Paste it into the Vercel Access Token field in the wizard.

You can delete the token immediately after setup completes.

Optional — Add a GitHub Token

The wizard also has an optional GitHub Token field. It lets you install new modules from the Modules page: Vercel's filesystem is read-only, so ARI installs modules by committing them to your GitHub repository — your repo is detected automatically.

1. Create a fine-grained token at github.com/settings/personal-access-tokens, scoped to your ARI repository with Contents: Read and write permission.
2. Paste it into the GitHub Token field in the wizard. Like the Vercel token, it is written to your project's environment variables and never stored or logged by the wizard.

Skip this now and you can add it anytime as a GITHUB_TOKEN environment variable in Vercel.

Step 5 — Configure & Deploy

In the wizard's Deploy step, enter your database connection string, your Vercel access token, confirm the auto-generated authentication secret, and optionally paste a GitHub token. Then click Configure & Deploy. ARI will:

1. Save your configuration to the Vercel project's environment variables (secrets are stored write-only).
2. Trigger a fresh production deployment so the new settings take effect.
3. Wait for the new deployment to go live (usually 1–3 minutes), then send you to the sign-in page.

Sign in with the admin email and password you chose — your account and database tables are created automatically on first sign-in.

After Setup

• First-run credentials. The admin email and password are stored as one-time environment variables and ignored once your account exists. You can safely delete ARI_FIRST_RUN_ADMIN_EMAIL and ARI_FIRST_RUN_ADMIN_PASSWORD in your Vercel project's Settings → Environment Variables.
• File storage. Vercel's filesystem is read-only and ephemeral, so uploaded files do not persist there. Configure a storage provider (S3, Cloudflare R2, or Supabase Storage) via environment variables — see Storage.
• Installing modules. Module installs on Vercel are committed to your GitHub repository, so they need a GitHub token. If you skipped it in the wizard, add a GITHUB_TOKEN environment variable (a fine-grained token scoped to your ARI repository with Contents: Read and write) in your Vercel project's Settings → Environment Variables — see Optional — Add a GitHub Token.
• Preview deployments share the same database as production.

Managed Setup

Prefer not to deal with infrastructure? The Managed Setup plan includes full hosting on your own custom domain, daily backups, and professional setup. Contact hello@ari.software for details.

Next Steps

• Authentication — Secure your instance
• Storage — Configure durable file storage
• Security — Harden your deployment