AI Recipient & Field Detection (Self-hosting)

Configure Google Vertex AI so Documenso can detect recipients and fields automatically.

Overview

This guide covers how to enable the AI recipient and field detection features when you self-host Documenso.

What This Enables

Detect recipients from uploaded PDFs (roles, names, emails when present).
Detect and place fields (signature, initials, name, email, date, text, number, radio, checkbox) onto draft envelopes.
Built-in rate limits (3 requests per minute per IP) to prevent abuse.

Prerequisites

A Google Cloud project with the Vertex AI API enabled and billing active.
A Vertex AI Express API key with access to Gemini models (create via the Vertex AI Express flow and manage keys in API keys).
Documenso version that includes the AI detection feature and the corresponding database migration.

Configure Environment Variables

Add these variables to your deployment .env (or secret manager):

GOOGLE_VERTEX_PROJECT_ID="<your-gcp-project-id>"
GOOGLE_VERTEX_API_KEY="<your-vertex-api-key>"
# Optional, defaults to "global"
GOOGLE_VERTEX_LOCATION="global"

Use a region close to your users if you need data residency considerations (e.g. europe-west1). If you omit the location, Documenso uses global. Not all models are available in every region; if a model is unavailable, switch to a supported region.

Deploy with the Published Container

Use the official Documenso image (DockerHub or GHCR) and supply the Vertex env vars above.
Ensure migrations run on startup (the container runs prisma migrate deploy in production mode).
Restart the container after adding or changing Vertex env vars.