Self-hosting

Hosted wgw-deploy uses the public API at https://deploy.wgw.lol. The hosted service stores project metadata and deploy assets in the service operator’s Cloudflare account and serves generated domains under wgw.lol.

Self-hosting runs the same deploy API and static Worker in your own Cloudflare account. You own the domain, tokens, storage, logs, limits, Cloudflare billing, and operational risk.

Components

The current repository has two Cloudflare-facing apps:

apps/deploy.wgw.lol: the deploy API and docs site. Its Worker name is configured as wgw-deploy-api.
apps/static-worker: the static asset Worker. Its Worker name is configured as wgw-static.

The deploy API publishes assets and manifest updates into the configured static Worker.

Required Cloudflare resources

A self-hosted install needs:

A Cloudflare account id.
A base domain served by Cloudflare, with routes for the base domain and wildcard subdomains.
A KV namespace bound to the deploy API as DEPLOYS.
A static Worker with Workers Assets enabled.
A deploy API Worker running the Astro Cloudflare build.
PUBLIC_ORIGIN set to the public base origin for generated deploy domains.
CLOUDFLARE_WORKER_NAME set to the static Worker name.
CLOUDFLARE_ZONE_ID when external custom domains are supported.

The checked-in hosted config uses wgw.lol and *.wgw.lol routes for the static Worker. A self-hosted install should replace those with your own base domain.

The static Worker is only the Workers Assets holder and final fallback. It does not route tenants in code. Configure Cloudflare URL Rewrite Rules before the static Worker so generated subdomains, revision subdomains, and custom-domain traffic resolve to the matching asset prefix, for example <project>.<base>/* to /<project>/* and external custom domains to /<lowercase-host>/*.

API tokens

Use narrow Cloudflare API tokens and keep the two roles separate:

CLOUDFLARE_WORKERS_API_TOKEN: account-scoped access for the deploy API to create Workers Assets upload sessions and publish the configured static Worker.
CLOUDFLARE_ZONE_API_TOKEN: zone-scoped access for the deploy API to create, read, and delete Cloudflare Custom Hostnames in CLOUDFLARE_ZONE_ID.

The zone token is only needed for external custom-domain support. Generated subdomains under your base domain still require the static Worker routes.

Cloudflare’s permission names can change. In the dashboard, choose the least-privilege permissions that cover the exact API calls above.

Point the CLI at your install

The CLI defaults to hosted:

npx wgw-deploy

For self-hosting, point it at your deploy API:

WGW_API_URL=https://deploy.example.com npx wgw-deploy

Local project state still lives in the CLI config directory, and the project API token returned by your API is stored there.

Hosted vs self-hosted

Hosted means:

No Cloudflare account is required by the deployer.
Deploys and metadata live in the hosted service’s Cloudflare account.
Generated domains use wgw.lol.
Limits and availability are controlled by the hosted service and Cloudflare.

Self-hosted means:

You supply the Cloudflare account, zone, routes, KV namespace, Workers, and API tokens.
You control generated domains, DNS, retention, deletion, logs, and observability.
You pay Cloudflare directly.
You are responsible for securing the tokens and complying with the source license.

License note

The repository is licensed under FSL-1.1-ALv2. Internal self-hosting is part of the license’s permitted-purpose shape, but offering the same or substantially similar functionality as a commercial product or service can be a competing use. Read the license files for the controlling terms. This is not legal advice.