Hosted deployments

For native containers on Northflank, Render, and Heroku, see container hosting.

GPROXY provides deployment templates for Cloudflare Workers, Netlify, and Vercel. They download prebuilt release bundles, so no Rust installation is needed. The console and API share your deployment domain; the console is at /console/.

Choose a platform

Platform	Platform database	Existing database	WebSocket / Realtime in this template
Cloudflare Workers	D1, created during deployment	libSQL / Turso	Supported
Netlify Functions	Netlify Database	PostgreSQL	Not supported
Vercel Functions	PostgreSQL product selected during deployment	PostgreSQL	Supported (platform Beta)

For HTTP and SSE streaming, you can use any template. For WebSocket or Realtime, choose Cloudflare Workers, Vercel Functions (WebSocket Beta), or a CLI / container deployment.

Cloudflare runs WASM; the other two platforms run the native serverless executable. They share GPROXY’s management API and console, while database types, function duration, and request size limits depend on the platform.

Prepare the password and encryption key

Every platform needs these two settings:

Setting	Value
GPROXY_ADMIN_PASSWORD	A login password of at least 8 characters
GPROXY_MASTER_KEY	A 32-byte key for encrypting upstream credentials, encoded as 64 hex characters or base64

You can generate a master key with openssl rand -hex 32. Save it and use the same value for updates and redeployments.

The username defaults to admin; set GPROXY_ADMIN_USER to choose another. The password setting is applied on startup: a same-name user’s password is updated first; if no name matches, administrator 0 is recovered and given the configured name and password. See administrator setup and password overrides.

If you are using an existing database, you will also need its connection details. Each platform’s steps are below.

Cloudflare Workers

Use an external libSQL / Turso database

Use the deploy button for D1, or the external-database link for an existing libSQL/Turso database.

1. Open your chosen entry and connect your GitHub or GitLab account.
2. For D1, choose a database name; Cloudflare creates and binds it. For an external database, enter GPROXY_DATABASE_URL and GPROXY_LIBSQL_TOKEN. That entry does not create D1.
3. Enter the administrator password and master key, keep npm run build and npm run deploy, and deploy.

A Turso URL can use libsql://your-db.turso.io or its HTTPS equivalent. This connection uses libSQL’s HTTP interface, not a PostgreSQL connection string.

An existing D1 deployment can also switch to libSQL through these variables. GPROXY_DATABASE_URL takes precedence over D1. Changing the connection selects a different database; it does not migrate existing data.

For Wrangler deployment or custom Workers configuration, see manual Cloudflare deployment below.

Netlify

Use an existing PostgreSQL database

Use the deploy button for Netlify Database, or the external-database link for an existing PostgreSQL database.

1. Open your chosen entry, authorize the repository, and enter the administrator password and master key.
2. For Netlify Database, the template reads the platform connection; no manual connection string is needed. For 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 looks like postgresql://user:password@db.example.com/gproxy?sslmode=require. Use the actual connection details supplied by your database service.

Both entries use the same Netlify template. Netlify may still provision a platform database when you supply an external connection; GPROXY gives GPROXY_DATABASE_URL precedence.

Vercel

Use an existing PostgreSQL database

Use the deploy button if you need a new database, or the external-database link for an existing PostgreSQL database.

1. Open your chosen entry. For a platform database, select and attach a PostgreSQL product when prompted. The external-database entry does not require a database product installation.
2. Enter the administrator password and master key. For an existing database, also set GPROXY_DATABASE_URL.
3. Keep the template’s build command and vercel.json, then deploy.

Platform connections are read from DATABASE_URL or POSTGRES_URL. If your product uses another variable name, put its connection string in GPROXY_DATABASE_URL.

This template uses Node.js Functions. Do not switch it to Edge Runtime.

Sign in and make a request

After deployment, open https://your-domain/console/ and sign in with admin (or your chosen username) and the configured password.

Add a provider and credential in the console. Test the credential, create a model route and gateway API key, then follow Your first request. Clients use your deployment URL, such as https://gateway.example.com/v1, and authenticate with the gateway API key.

If Netlify or Vercel returns 503, check the function logs and confirm that the database is attached, its connection string works, and the password and master key are set. The PostgreSQL account also needs permission to create the gproxy schema and application tables.

Updates and runtime limits

Configuration, accounts, and usage live in the database. Keep the database and master key when updating. Templates download the latest stable release by default and verify SHA-256. Clear the platform build cache and redeploy to upgrade. Set the build environment variable GPROXY_RELEASE_VERSION to a release tag only when you want to pin a version. The release must include the matching platform bundles. Hosted deployments do not use the console’s in-place binary updater.

All templates support HTTP and SSE; Netlify Functions rejects WebSocket upgrades. Vercel uses the platform’s WebSocket Beta. Function duration limits or instance eviction can still disconnect WebSockets, so clients must handle reconnection. Long-running inference, large files, and high concurrency remain subject to platform limits. Check the current Netlify Functions and Vercel Functions allowances for your workload.

These two templates do not configure file storage. For S3/R2 or publicly downloadable files, use a custom Workers build as described below, or the CLI. On Netlify and Vercel, GPROXY_PUBLIC_BASE_URL fixes the public URL. Without it, Netlify and Vercel use the production URL the platform provides; elsewhere OAuth endpoints answer from each request’s Host and publication links stay disabled.

Manual Cloudflare deployment

Use a release bundle

Download gproxy-edge-cloudflare.zip, extract it, and enter the cloudflare directory. It contains the Worker, console, and wrangler.toml.

For D1, install dependencies and create the database:

pnpm install
pnpm exec wrangler d1 create gproxy

Put the returned database ID in wrangler.toml, keeping the binding name DB:

[[d1_databases]]
binding = "DB"
database_name = "gproxy"
database_id = "replace-with-your-database-id"

Set the master key and administrator password, then deploy:

pnpm exec wrangler secret put GPROXY_MASTER_KEY
pnpm exec wrangler secret put GPROXY_ADMIN_PASSWORD
pnpm exec wrangler deploy --dry-run
pnpm exec wrangler deploy

For libSQL, set GPROXY_DATABASE_URL and GPROXY_LIBSQL_TOKEN and remove the unused D1 binding. The release bundle enables libSQL; retain that feature when building your own. GPROXY creates its tables on first startup, so no separate Wrangler SQL migrations are needed.

Workers configuration and static assets

GPROXY_CONFIG accepts a JSON configuration document. Named secrets override their corresponding fields. This example uses D1 and sets a public URL:

[vars]
GPROXY_CONFIG = '{"store":{"kind":"d1","binding":"DB"},"cache":{"kind":"store"},"public_base_url":"https://gateway.example.workers.dev"}'

Workers Assets serves the console. Keep the template’s routing configuration so /console/ uses static assets and other requests reach the gateway:

[assets]
directory = "./public"
binding = "ASSETS"
not_found_handling = "single-page-application"
run_worker_first = ["/*", "!/", "!/console", "!/console/*"]

Workers supports D1 or libSQL, without local SQLite, TCP databases, or local file directories. For S3/R2, enable the s3 feature at build time and set GPROXY_S3_ACCESS_KEY_ID, GPROXY_S3_SECRET_ACCESS_KEY, and the file-storage configuration. See the configuration reference for the fields.

Build from source

Run from the repository root:

rustup target add wasm32-unknown-unknown
cargo install worker-build
pnpm --dir console install --frozen-lockfile
pnpm --dir deploy/cloudflare install
pnpm --dir deploy/cloudflare build
pnpm --dir deploy/cloudflare check

See Building from source for build and packaging options.