/console/.
Choosing a platform
All three serve HTTP and SSE streaming. If clients need WebSocket or Realtime, choose Cloudflare Workers or Vercel, or run the CLI or a container instead.
On Cloudflare the gateway runs as WebAssembly inside the Worker. On Netlify and Vercel a small Node.js function starts the native
gproxy-serverless executable and forwards requests to it. The management API and the console are the same on all three; database types, function duration and request size limits come from the platform.
Before you deploy
Every template asks for two secrets. Prepare them first and keep a copy.GPROXY_ADMIN_PASSWORD: the console password, at least 8 characters.GPROXY_MASTER_KEY: a 32-byte key that encrypts upstream credentials in the database, written as 64 hex characters or base64. Generate one withopenssl rand -hex 32.
admin unless you also set GPROXY_ADMIN_USER. The password is applied on every startup: if a user with that name exists, only that user’s password is changed; if none does, administrator 0 is re-enabled and given the configured name and password. The full rules are under Bootstrap in the configuration reference.
If you connect an existing database rather than a platform one, have its connection details ready as well. Each platform’s section says which values it needs.
Cloudflare Workers
- Open the entry you want and connect your GitHub or GitLab account.
- For D1, choose a database name; Cloudflare creates the database and binds it as
DB. For an external database, enterGPROXY_DATABASE_URLandGPROXY_LIBSQL_TOKEN. - Enter the administrator password and the master key. Leave the build command as
npm run buildand the deploy command asnpm run deploy, then deploy.
libsql://your-db.turso.io or as the equivalent HTTPS address. The Worker talks to libSQL over its HTTP interface, so a PostgreSQL connection string does not work here.
A D1 deployment can be switched to libSQL later by setting the same two variables; GPROXY_DATABASE_URL takes precedence over the D1 binding. Switching the connection selects a different database. Nothing is copied from D1.
To deploy with Wrangler yourself or change the Worker configuration, see Deploying to Cloudflare manually.
Netlify
- Open the entry you want, authorize the repository, and enter the administrator password and the master key.
- With Netlify Database, the function reads the platform’s connection string and you enter nothing. With an existing database, enter its PostgreSQL connection string as
GPROXY_DATABASE_URL. - Keep the template’s build command and Functions configuration, then deploy.
postgresql://user:password@db.example.com/gproxy?sslmode=require; use the values your database provider gives you.
Netlify may still provision a platform database when you supply an external connection. It does no harm: GPROXY_DATABASE_URL is checked first.
Vercel
GPROXY_DATABASE_URL instead.
- Open the entry you want. With the deploy button, select and attach a PostgreSQL product when prompted.
- Enter the administrator password and the master key, and for an existing database also
GPROXY_DATABASE_URL. - Keep the template’s build command and
vercel.json, then deploy.
GPROXY_DATABASE_URL, then DATABASE_URL, then POSTGRES_URL. If the product you attached sets a variable with another name, copy its value into GPROXY_DATABASE_URL.
The template uses Node.js Functions. Do not switch it to the Edge Runtime; the function starts a native executable, which the Edge Runtime cannot do.
Signing in
- Open
https://your-domain/console/. The bare domain leads there as well. - Sign in as
admin(or the name you set inGPROXY_ADMIN_USER) with the configured password. - Add a provider and a credential, and test the credential.
- Create a model route and an API key, then send a request as described in Your first request.
https://gateway.example.com/v1, and authenticate with the API key you created.
On Netlify and Vercel, a request that arrives while the gateway cannot start is answered with status 503 and the message GPROXY is unavailable. Check the deployment database and secrets in the platform console. Look at the function logs. The usual causes are a database that is not attached, a connection string that does not start with postgres:// or postgresql://, or a missing password or master key. The executable must report that it is ready within 45 seconds; a database that cannot be reached shows up as a startup timeout. The PostgreSQL account also needs permission to create the gproxy schema and the application tables.
Updating
Configuration, accounts and usage live in the database, so an update only replaces the code. Keep the database and the master key. The D1 template and the Netlify and Vercel templates download the latest stable release at build time and verify its SHA-256 checksum against the release’sSHA256SUMS. To upgrade, clear the platform’s build cache and redeploy. To stay on one version, set the build environment variable GPROXY_RELEASE_VERSION to a release tag; that release must include the bundle for your platform.
The external-database Cloudflare template is different: its prepare-release.mjs names a fixed release tag (currently v4.2.0) and ignores GPROXY_RELEASE_VERSION. To upgrade it, change the tag in that file in the repository the deployment created, then redeploy.
Hosted deployments do not use the console’s in-place binary updater.
Runtime limits
Every template handles HTTP and SSE. Netlify Functions do not accept WebSocket upgrades; the gateway answers such requests with status 501. Vercel supports WebSocket through its WebSocket Beta. Function duration limits and instance recycling can still close a WebSocket on any platform, so clients must reconnect. The Vercel template setsmaxDuration to 300 seconds in vercel.json. Long inference requests, large files and high concurrency remain subject to each platform’s limits; check the current Netlify Functions and Vercel Functions allowances against your workload.
The Netlify and Vercel templates do not configure file storage. For S3 or R2, or for files that clients download by public link, build a custom Worker as described below, or run the CLI.
OAuth endpoints and published file links need the gateway’s public address. On Netlify and Vercel, set GPROXY_PUBLIC_BASE_URL to fix it; without it, the function uses the production URL the platform reports. When no public address is known, OAuth endpoints answer with each request’s own Host and publication links stay disabled. On Workers, set public_base_url in GPROXY_CONFIG (see below).
Deploying to Cloudflare manually
From the release bundle
Downloadgproxy-edge-cloudflare.zip from a release, extract it, and change into its cloudflare directory. It contains the built Worker, the console and a wrangler.toml.
For D1, install the dependencies and create the database:
wrangler.toml. Keep the binding name DB:
GPROXY_DATABASE_URL and GPROXY_LIBSQL_TOKEN and remove the unused D1 binding. The release bundle is built with libSQL support; keep that feature enabled if you build your own.
GPROXY creates its tables on first startup. You do not need to run Wrangler SQL migrations.
Worker configuration
GPROXY_CONFIG holds a JSON configuration document. Secrets with their own names, such as GPROXY_MASTER_KEY, override the matching fields. This example uses D1 and sets the public address:
/console/ is served from the assets and every other path reaches the gateway:
s3 feature, set GPROXY_S3_ACCESS_KEY_ID and GPROXY_S3_SECRET_ACCESS_KEY, and add the file storage fields to the configuration; they are listed in the configuration reference.
Building from source
From the repository root:build compiles the Worker into deploy/cloudflare/build/ and the console into deploy/cloudflare/public/; check is a Wrangler dry run. Building from source covers the other build and packaging options.