Install and configure login
Run the installer and configure how people sign in. Press Enter to accept a suggested value, or type your own. Names like company and example.com are placeholders.
On this pageRun the interactive installer · Choose names and domains · Configure login methods
Requires: login or token
The installer needs a Cloudflare management API token. Never paste it into chat or code.
This step starts the interactive install for workers.dev testing. Choose your login method below.
void platform install --workers-devExample output: The interactive installer starts.
For a domain installation or Access setup, the platform guides you to create a management API token and paste it into a masked prompt. Browser login can preview DNS. It cannot change DNS or configure Access. The token-creation link preselects the permissions for your choices. When using an existing domain, change the zone policy from All Domains to Specified Domains and select your zone, as the CLI prompt describes. No shell environment variable is needed for interactive installation.
Use an existing management token from the shell
To use an existing token instead of the prompt, set CLOUDFLARE_API_TOKEN. In Bash or zsh, read it without showing it or saving it in history.
Run these three steps in the same terminal. Later steps use the token read in step 1.
Read the token into a shell variable without showing it.
shprintf 'Cloudflare management API token: ' read -rs CLOUDFLARE_API_TOKENExample output: a prompt. Your input is hidden.
End the prompt line and export the token read in step 1.
shprintf '\n' export CLOUDFLARE_API_TOKENExample output: a blank line.
Start the installer. It uses the token exported in step 2.
shvoid platform installExample output: the interactive installer starts.
In PowerShell:
$env:CLOUDFLARE_API_TOKEN = [System.Net.NetworkCredential]::new('', (Read-Host 'Cloudflare management API token' -AsSecureString)).Password
void platform installAfter reviewing --plan, run void platform install and select your saved plan, or run the command printed under Next, run this command to install the platform. Both carry your choices into installation and check the current Cloudflare state. Review the refreshed plan. At Apply this plan?, Yes is selected; press Enter to continue to the credential prompts, or choose No to stop. The SDK opens the relevant setup pages and provides fallback links in the terminal. It reuses values you have already supplied.
Saved plans contain your installation choices, including paths to any authentication configuration or custom runtime. They hold no secrets and no approval to install. Declining the plan or cancelling management-token setup keeps those choices for your next attempt.
Choose login methods
The installer offers GitHub, Google, generic OIDC and Cloudflare Access login. Select every method you want. None is selected at first. Cloudflare Access protection is a separate choice from Access login. The GitHub OAuth steps below apply when you select GitHub login.
Choose who can access apps
The installer asks Who should be able to access deployed apps?
- Same people allowed by the platform’s Access policy reuses your selected company identities and policies. This is recommended when platform Access protection is enabled.
- Anyone — public apps allows public visits.
- Choose a different Access policy selects separate company rules for apps. Without platform protection, this option is Set up Cloudflare Access protection.
The plan shows the default app access. The SDK sets up and verifies app access before opening traffic. New projects inherit the default. If setup stops, use the printed resume command. Existing installations retain their administrator settings during upgrades.
App protection uses the account hosting your platform. If platform login or protection uses another account, select equivalent identity providers and policies in the hosting account when prompted. Use the app domain’s apex or a workers.dev hostname for the API so it stays outside the app wildcard.
The SDK checks account-wide Default-Deny during setup. For public apps in an account that requires Access rules, it creates rules for each app and its verified custom domains. Other subdomains keep their existing access rules. It leaves account-wide Default-Deny enabled and does not bypass the platform API or proxy.
App rules need Access: Apps and Policies Edit and Organizations, Identity Providers, and Groups Read. The SDK stores this management token encrypted for future apps and domain changes. The installer asks before retaining a setup-only token for that purpose, or guides you to create a dedicated token. Public apps without Default-Deny need no ongoing Access-management credential.
For scripts, use --app-access public|platform|custom. When app rules are needed, supply VOID_PLATFORM_APP_ACCESS_TOKEN, or add an appAccess section to your --auth-config file:
{
"appAccess": {
"mode": "custom",
"identityProviderIds": ["hosting-account-identity-provider-id"],
"policyIds": ["hosting-account-company-policy-id"],
"tokenEnv": "APP_ACCESS_API_TOKEN"
}
}Keep the file’s existing connections configuration. For mode: "platform", same-account identity and policy selections are reused. Headless setup needs an explicit app-management token. It never silently keeps an installer-only token.
Finish login configuration
For Google, create an OAuth client and register the printed callback URL. You can limit it to named Google Workspace domains. For OIDC or Access login, provide the issuer URL, client ID and client secret. Select Company-approved users when the configured company policy should allow colleagues to create accounts automatically without individual invitations.
When using the configurable setup, installation prints a one-time setup code and a /setup URL. Enter the code, authenticate with the chosen administrator method, and review the identity before confirming its administrator role. That method is turned on. Other selected methods are saved as pending, to test and enable in Settings. No GitHub account is required for a Google-only or OIDC-only installation.
For scripts, pass --auth-config <path>. The file holds nonsecret config and env-variable references for secrets. For example:
{
"connections": [
{
"configuration": {
"id": "google",
"kind": "google",
"label": "Company Google",
"clientId": "your-google-client-id",
"allowedDomains": ["example.com"]
},
"clientSecretEnv": "GOOGLE_CLIENT_SECRET"
}
],
"administratorConnectionId": "google",
"admission": {
"mode": "company",
"connections": ["google"],
"access": false
}
}--plan reads this file without the referenced secret. Supply the secret from your secret manager when you apply the installation.
Cloudflare access
Choose Access login, platform protection, or both. Protection can also be used with GitHub or another login method. With company-approved signup, a colleague who passes the company gate can create an ordinary account using GitHub even when their GitHub email differs from their company email.
Your identity provider determines how employees sign in, such as through Okta or Google Workspace. Your Access policies determine who can reach the platform and which MFA or device requirements apply.
Automatic setup uses an existing Zero Trust organization, selected identity providers, and existing company policies. The SDK creates dedicated applications and a scoped service token for protected installation checks. It preserves your company policies, including device and MFA requirements.
If no policy fits, choose Allow my company’s email domain in the policy list and enter your domains. The SDK creates that Allow policy in your account and keeps it there for reuse; you can add MFA or device rules to it in Cloudflare later. For identity-provider groups or other rules, choose Create in Cloudflare and follow the printed steps.
An Allow policy must name who may sign in: emails, email domains or lists, identity-provider groups (Okta, Microsoft Entra ID, Google Workspace, GitHub organizations, or SAML), authentication contexts, members of a Cloudflare account, or Access groups built from them. Microsoft Entra ID groups and authentication contexts count only when they come from an identity provider you select. A login method also counts when it is one of the identity providers you select and uses Cloudflare's connector for a company directory: Microsoft Entra ID, Okta, OneLogin, PingOne, Centrify, Google Workspace, or the Cloudflare login with Restrict to account members turned on. Policies that allow everyone, any service token, or bypass Access are rejected, and so are policies that rely only on One-time PIN, a public login such as GitHub, or a login added with the generic OpenID Connect or SAML option, even one that fronts your company directory. The SDK cannot tell who can sign in through a generic login; add a Require rule such as Emails ending in your company domain to that policy.
The setup credential needs Access: Apps and Policies Write and Access: Organizations, Identity Providers, and Groups Read in the identity account. Creating protection also needs Access: Service Tokens Write. For setup in the installation account, the initial management-token link includes these permissions. The SDK checks Access reads before provisioning and reuses that management token during Access setup, so you do not need a second API token. For applications in another account, provide a token scoped to that identity account when asked. Scripts can supply an explicit override through VOID_PLATFORM_ACCESS_SETUP_TOKEN. The platform's runtime token does not need Access management permissions. See Cloudflare's Access API and service-token permissions.
This step automates Access setup. Add this to the authentication config file.
{
"protection": true,
"cloudflareAccess": {
"mode": "create",
"identityProviderIds": ["your-company-identity-provider-id"],
"policyIds": ["your-company-allow-policy-id"]
}
}Keep the file's connections list from the example above, or use a connection with {"id":"access","kind":"cloudflare-access","label":"Company Access"} to create Access login as well. Omit protection for login-only setup.
To connect applications managed elsewhere, select Use Access applications your company already manages. Enter the account that owns the Access applications; it can differ from the account hosting the platform. Scripts use mode: "existing", optional accountId, and loginApplicationId and/or protectionApplicationId. For login, set loginClientSecretEnv. For protection, supply serviceToken with id, clientIdEnv, and clientSecretEnv for a token already admitted by the application. The selected policies must cover both printed API and proxy origins. Connecting existing resources needs read access to their applications, policies, organization, identity providers, groups, and service tokens; the platform leaves their policies unchanged.
Access login alone can connect to another account using only its issuer, client ID, and secret, without a cloudflareAccess block or Cloudflare management token. Follow Cloudflare's OIDC application guide and register the exact callback printed by the platform.
GitHub
For GitHub login:
- The installer opens GitHub's new OAuth App form when it needs OAuth credentials. Sign in as the account that will own the login integration.
- Set Application name to your platform's display name and Homepage URL to the API URL the platform just printed.
- Set the Redirect URI (also called Authorization callback URL) to the exact printed URL ending in
/auth/callback, then register the application. This URL is now pinned in your saved draft and remains the same if credential setup is interrupted. - Save the Client ID, generate a Client Secret, and save that too. GitHub's registration guide describes the form.
This OAuth App handles sign-in.
Finish installation
The installer collects your runtime token, PostgreSQL URL, login-provider credentials, and R2 credentials, and generates the signing and encryption keys. It masks secret values and saves setup progress encrypted through your system keychain. Keep a password-manager copy for recovery on another machine.
Once installation finishes, open the printed admin dashboard link. For GitHub-only setup, sign in as the administrator selected during installation. For configurable login, use the one-time /setup code to confirm the administrator’s identity. Use the printed API URL to connect and deploy an app.
This step removes a management token you supplied through the shell.
unset CLOUDFLARE_API_TOKENExample output: No output. The token is removed from the shell.
In PowerShell, use Remove-Item Env:CLOUDFLARE_API_TOKEN. Keep the saved token for future maintenance.
If setup pauses for DNS or is interrupted
If the platform created a zone, it stops in waiting-for-dns and prints nameservers. Set those at your registrar, wait for the zone to become active, then resume using the installation ID printed by the platform:
void platform install --resume --name <installation-id>Example output: The interrupted installation resumes.
Resume reuses the saved management token and asks for one if it is missing or rejected by Cloudflare. You can override it through CLOUDFLARE_API_TOKEN. When using a source build, also pass the same --runtime directory. Resume uses the saved checkpoint and original secrets; do not start a second installation or generate replacement keys. If setup stopped before a checkpoint was saved, rerun void platform install and select your saved plan, or rerun the original command.
You can also rerun void platform install and choose Continue setup for an unfinished installation. For non-interactive recovery, use --resume --name <id>. Manage completed platforms with platform status, repair, or upgrade.
Resume restores your selected Hyperdrive. If that selection is missing from the saved checkpoint, add --hyperdrive <existing-id> when resuming, using the same configuration you originally selected.
If Cloudflare rejects a saved runtime token during continued credential setup, the platform opens the token page and asks for a replacement in the same run. Network or service failures do not discard saved tokens. Tokens supplied through the environment must be corrected there instead.
