Platform installation
These commands install a self-hosted SDK platform in your Cloudflare account, set its domain and manage its lifecycle.
On this pageInstall a platform · Set the platform domain · Upgrade, disable or remove it
Requires: Cloudflare login
The command uses your Cloudflare browser login, or CLOUDFLARE_API_TOKEN in CI. Keep tokens in your secret manager, never in project files.
Now you will start the installer.
void platform install [options] [--yes]Example output: the install plan, then progress for each step.
| Option | Purpose |
|---|---|
--name <slug> | Installation name used in void-<name>-<role> resource names; choose an unused name |
--display-name <name> | Human-readable platform name |
--account <id> | Cloudflare account id |
--auth-config <path> | Login methods, signup policy, and environment references for provider secrets |
--login-methods <methods> | Comma-separated github, google, oidc, or cloudflare-access login methods |
--access-protection | Protect the platform UI and APIs with Cloudflare Access |
--no-access-protection | Skip Cloudflare Access protection |
--app-access <public|platform|custom> | Public apps, the platform's Access policy, or separately selected app policies |
--hyperdrive <create|id> | Create Hyperdrive or use the specified existing configuration |
--application-domain <domain> | Base domain for deployed apps |
--workers-dev | Explicit testing mode; add an application domain later |
--zone <domain> | Cloudflare zone containing the application domain |
--dedicated-zone | Add zone-wide catch-all routes; valid only when the app domain is the whole zone |
--no-dedicated-zone | Skip zone-wide application catch-all routes |
--control-plane-domain <domain> | Optional API custom hostname; defaults to workers.dev |
--no-control-plane-domain | Use the default workers.dev API hostname |
--dashboard-url <origin> | HTTPS origin of an optional dashboard deployed separately |
--plan | Preview Cloudflare changes and save installation choices locally |
--resume | Continue the matching checkpointed installation |
--runtime <path> | Deploy a locally built, integrity-checked runtime directory |
--yes | Acknowledge Cloudflare changes in non-interactive use |
For a first install, follow Install a Void Platform. The interactive installer recommends a domain. It also offers Use workers.dev for testing. The SDK creates the platform infrastructure and tables.
Both modes need external PostgreSQL and a login method. Select every login method you want. None are selected at first. A non-interactive install uses GitHub when no login config is given. --workers-dev skips zone, DNS and certificate work. It cannot be combined with --application-domain, --zone or --dedicated-zone.
Read-only plans, workers.dev installs with the default API hostname and supported lifecycle commands can use Cloudflare browser login and the system keychain. An install that writes DNS or creates a zone needs a management API token. The installer helps you create one and paste it into a masked prompt. Scripts use CLOUDFLARE_API_TOKEN or CF_API_TOKEN from a secret store.
The installed platform needs a separate runtime token to create resources for apps. The installer asks for it and the other setup values. For non-interactive installs, inject the variables listed in Install from CI.
To turn on email during install or upgrade, set both VOID_EMAIL_SENDER_DOMAIN and VOID_EMAIL_SHARED_ZONE_ID. The SDK records the pair for later upgrades. Setting only one is an error.
Use --dashboard-url https://dash.example.com when you deploy the optional user dashboard separately. The URL must be an HTTPS origin with no credentials, path, query or fragment. The SDK allows that origin's login callbacks and saves it for later maintenance. It does not deploy a dashboard Worker. Without the flag, an existing install keeps its saved dashboard origin.
--plan previews resource names, login methods, default app access, the login callback URL, database config and credential needs. An existing Hyperdrive shows its database and config name. Setup links appear during guided credential setup.
A finished preview saves your non-secret choices locally. Run void platform install again to pick a saved plan and see a fresh check of Cloudflare state. Or run the install or resume command printed at the end. Started installs use their saved checkpoints. Finished installs do not appear in the chooser. For login config, use --auth-config or --login-methods with the Access protection flags.
App access is set before traffic opens. With platform protection on, the installer suggests reusing its company policy. Otherwise apps are public by default. Use --app-access custom to pick separate hosting-account policies. Public apps in a Default-Deny account get scoped public Access rules. When needed, the installer explains and collects the encrypted management credential. Scripts pass VOID_PLATFORM_APP_ACCESS_TOKEN or appAccess.tokenEnv in the auth file. Upgrades keep admin settings.
New resources use void-<name>-<role> names. Choose an installation name that is not in use. The installer opens setup pages for missing credentials and reuses values you already gave.
During Access setup, choose existing company policies, or Create in Cloudflare for manual steps and a dashboard link. After you save the policy and confirm, the list reloads. Select the policy and continue in the same run.
When the platform creates the Access applications, Allow my company's email domain creates an Allow policy for the domains you enter and selects it. Refresh list reloads policies made in another window. Your identity-provider choice and valid policy selections are kept. If a selected policy does not limit sign-in to company identities, the platform explains why and asks again.
Install progress and partial credentials are saved locally and encrypted. Run the installer again to continue, or pass --resume --name <id>. Use lifecycle commands for finished installs.
Use an empty PostgreSQL database just for this installation. You can fix a failed first connection. Once the database is claimed or Hyperdrive exists, commands reject a different URL.
Choose whether the platform creates Hyperdrive or uses an existing one. An existing Hyperdrive must point to the platform database with SQL result caching off. Provide a database owner URL for migrations. See Use an existing Hyperdrive for setup and Install from CI for unattended inputs.
Recovery secrets are encrypted with your system keychain. Without a keychain, provide a base64-encoded 32-byte VOID_PLATFORM_RECOVERY_KEY. Keep the original credentials in protected CI secrets for recovery.
A new zone may wait for registrar delegation. Once it is active, resume the install. Use the installation ID from step 1's output.
void platform install --resume --name <installation-id>Example output: the install plan, then progress for each step.
See Self-host an SDK platform for prerequisites, token scope, the exact footprint, domain behavior and a full walkthrough.
void platform domain set
This command adds a domain to a workers.dev test platform. Now you will run it.
void platform domain set <domain> [--installation <id>] [--zone <domain>] [--dedicated-zone] [--plan] [--yes]Example output: the requested record, list, or a confirmation. Commands with --plan show the change without applying it.
Domain-based installs are still the recommended default. The command finds the zone when it can. After you confirm, it creates missing DNS and routes. It checks HTTPS and project Zero Trust protection before it makes the domain canonical. If DNS, certificates or protection are pending, run the same command again to resume. --plan is read-only. Non-interactive changes need --yes.
Existing workers.dev URLs keep working. The platform API origin, OAuth callback, projects and deploys do not change. The command checks that the runtime token has Cache Purge permission for the new zone. A disabled platform stays disabled. When you manage the platform from another machine, use the original database URL. Replacing an app domain that is already set is not supported. See Adding a Domain.
Lifecycle commands
Use these commands to recover, update, pause or remove an installation. Later commands take the installation ID or slug that discover or void platform list shows.
Now you will run void platform discover and void platform upgrade.
void platform discover [--account <id>] [--installation <id-or-name>]
void platform upgrade [id] [--runtime <path>] [--dashboard-url <origin>] [--plan] [--yes]Example output: the requested record, list, or a confirmation. Commands with --plan show the change without applying it.
Next, run void platform rollback and void platform repair.
void platform rollback [id] --runtime <earlier-path> [--from-runtime <current-path>] [--plan] [--yes]
void platform repair [id] [--runtime <path>] [--dashboard-url <origin>] [--auth-config <path>] [--plan] [--yes]Example output: the requested record, list, or a confirmation. Commands with --plan show the change without applying it.
Next, run void platform disable and void platform enable.
void platform disable [id] [--plan] [--yes]
void platform enable [id] [--runtime <path>] [--plan] [--yes]Example output: the requested record, list, or a confirmation. Commands with --plan show the change without applying it.
Next, run void platform uninstall.
void platform uninstall [id] [--plan] [--purge-data | --purge-resources] [--yes]Example output: the requested record, list, or a confirmation. Commands with --plan show the change without applying it.
discover --installation limits recovery and endpoint checks to one installation in a shared Cloudflare account.
Use the installation slug shown next to its name in void platform list. Installation IDs and saved connection IDs also work. Lifecycle commands need local installation records. Use discover to restore them on another machine. Leave out id when only one installation exists, or pick from the menu. Non-interactive commands need a slug or ID when there are several. Commands that change things also need --yes. --plan only previews.
To add or change a separately deployed dashboard after install, use repair --dashboard-url <origin> or upgrade --dashboard-url <origin>. Preview with --plan first. Existing Access protection must cover the dashboard origin before maintenance can continue. See Optional Dashboard.
While first admin setup is pending, repair --auth-config <path> replaces the login settings from a file in the install format. It prints a new setup code. Interactive repair offers the same change with saved values filled in. Login methods and Access protection stay as installed. Run it on the computer that installed the platform. See First administrator sign-in fails.
After discovery on another machine, set VOID_PLATFORM_DATABASE_URL in that terminal. See Manage an installation from another machine for the secrets needed to recreate a missing Worker.
| Command | Behavior |
|---|---|
discover | Verifies remote ownership and restores local installation records without downloading secrets |
repair | Recreates missing resources owned by the installer |
upgrade | Deploys the selected runtime and supported pending migrations |
rollback | Restores a declared-compatible earlier runtime without reversing PostgreSQL migrations |
disable | Blocks app traffic and the platform API without removing data; only admin status and sign-in stay available |
enable | Redeploys and verifies the platform Workers, then restores traffic |
uninstall | Blocks traffic and removes eligible resources, retaining data by default |
Repair and upgrade keep a disabled state. New, resumed and previously disabled installs block user traffic until all target Workers pass checks. The installer's health probes still run. Routes and custom domains stay attached.
--runtime selects a custom platform build. Relative paths start from your current folder. The SDK checks the build before it changes anything. See Platform Development for creating one.
Without --runtime, the CLI uses its bundled platform version.
Platform migrations only move forward. The SDK checks compatibility before it updates the database. It tells you if you need an intermediate release first.
An upgrade finishes when the new Workers pass health checks. If the rollout fails, the platform tries to restore the previous Workers. A retry does not repeat finished migrations.
platform rollback restores a compatible earlier runtime. It does not undo database migrations. Pass its files with --runtime. If the installed version is custom, also pass it with --from-runtime. The SDK refuses incompatible targets.
If project Zero Trust is on and no platform user exists yet, uninstall first turns it off and deletes its Access applications. Run it on the computer that installed the platform.
Uninstall checks remote ownership before it removes anything. Data resources are kept unless you pass --purge-data. Workers, their Queues, R2, AI Gateway, DNS records, routes, custom domains, adopted resources, external PostgreSQL and zones are kept for manual review. --keep-zone is deprecated and does nothing. Uninstall always keeps zones.
--purge-resources includes --purge-data. It also deletes every other resource the installation created: Workers, Queues, R2, AI Gateway, the platform DNS record, routes, custom domains and installer-created Access resources. It only removes the Email Routing rules that send mail to the platform email gateway. Zones, adopted resources, external PostgreSQL, other Email Routing settings and API tokens are kept.
A route, custom domain, DNS record or Access resource that no longer matches the installation's record is kept and listed. The command refuses to start while projects remain or resource reads are denied. Grant the Edit permissions that --plan lists. Read checks cannot verify them, so a denied deletion can stop uninstall partway. Run the same command again to continue after an interruption. This also works after a plain or --purge-data uninstall stopped.
See Disable and Uninstall for the full removal policy and cleanup order.
