Skip to main content
GPROXY ships deployment templates for Cloudflare Workers, Netlify Functions and Vercel Functions. Use this page when you want a hosted gateway without running a server; for Docker, Render and Heroku, see Docker, Render, and Heroku. The templates download prebuilt release bundles at build time, so you do not need a Rust toolchain. The console and the API share the deployment’s domain, and the console is at /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 with openssl rand -hex 32.
The username is 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.
Use the same GPROXY_MASTER_KEY for every update and redeployment. Credentials sealed under one key cannot be opened with another, so a new key leaves every stored upstream credential unreadable.
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

Deploy to Cloudflare Use an external libSQL / Turso database The deploy button creates a D1 database. The second link deploys a variant that connects to an existing libSQL or Turso database and does not create D1.
  1. Open the entry you want and connect your GitHub or GitLab account.
  2. For D1, choose a database name; Cloudflare creates the database and binds it as DB. For an external database, enter GPROXY_DATABASE_URL and GPROXY_LIBSQL_TOKEN.
  3. Enter the administrator password and the master key. Leave the build command as npm run build and the deploy command as npm run deploy, then deploy.
A Turso URL can be written as 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

Deploy to Netlify Use an existing PostgreSQL database The deploy button uses Netlify Database. The second link opens the same template with a field for an external PostgreSQL connection.
  1. Open the entry you want, authorize the repository, and enter the administrator password and the master key.
  2. 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.
  3. Keep the template’s build command and Functions configuration, then deploy.
An external connection string looks like 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

Deploy with Vercel Use an existing PostgreSQL database The deploy button asks you to attach a new PostgreSQL product. The second link skips that and asks for GPROXY_DATABASE_URL instead.
  1. Open the entry you want. With the deploy button, select and attach a PostgreSQL product when prompted.
  2. Enter the administrator password and the master key, and for an existing database also GPROXY_DATABASE_URL.
  3. Keep the template’s build command and vercel.json, then deploy.
The function looks for a connection string in 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

  1. Open https://your-domain/console/. The bare domain leads there as well.
  2. Sign in as admin (or the name you set in GPROXY_ADMIN_USER) with the configured password.
  3. Add a provider and a credential, and test the credential.
  4. Create a model route and an API key, then send a request as described in Your first request.
Clients use the deployment URL as their base URL, for example 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’s SHA256SUMS. 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 sets maxDuration 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

Download gproxy-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:
Copy the database ID that Wrangler prints into wrangler.toml. Keep the binding name DB:
Store the master key and the administrator password as secrets, check the deployment, and deploy:
For libSQL instead of D1, set 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:
The console is served by Workers Assets, so loading it does not run the Worker. Keep the template’s routing so that /console/ is served from the assets and every other path reaches the gateway:
A Worker can use D1 or libSQL. It has no local SQLite, no TCP database connections and no local file directory. For S3 or R2 file storage, build with the 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.