Set up VibeSDK for local development and production deployment.

Make sure to read through the entire guide for important notes, and have all the required information ready before starting.

Current generated-app previews use SpaceDO, a Worker Loader binding, and Dynamic Workers. Cloudflare Artifacts is optional behind ENABLE_ARTIFACTS; it is not required for the default SQLite workspace filesystem. Previews do not require a sandbox container or persistent preview server.

Before getting started, make sure you have:

• Node.js (v18 or later)
• Cloudflare account with API access
• Cloudflare API Token with appropriate permissions

• Bun
• Custom domain configured in Cloudflare (for production deployment)

• Workers Paid Plan (for remote Cloudflare resources)
• Workers for Platforms subscription (for app deployment features)
• Advanced Certificate Manager (if using first-level subdomains)

The fastest way to get VibeSDK running is with our automated setup script:

# Bun is recommended. Install it first if needed.
curl -fsSL https://bun.sh/install | bash
# Then install dependencies and run setup
bun install
bun run setup

This interactive script will guide you through the entire setup process, including:

• Package manager setup (installs Bun automatically for better performance)
• Cloudflare credentials collection (Account ID and API Token)
• Domain configuration (custom domain or localhost for development)
• Remote setup (optional production deployment configuration)
• AI Gateway configuration (Cloudflare AI Gateway recommended)
• API key collection (OpenAI, Anthropic, Google AI Studio, etc.)
• OAuth setup (Google, GitHub login - optional)
• Resource creation (KV namespaces, D1 databases, R2 buckets, AI Gateway)
• File generation (.dev.vars and optionally .prod.vars)
• Configuration updates (wrangler.jsonc and vite.config.ts)
• Database setup (schema generation and migrations)
• Template deployment (example app templates to R2)
• Readiness report (comprehensive status and next steps)

The setup script will ask you for the following information:

1. Account ID: Found in your Cloudflare dashboard sidebar

2. API Token: In you Cloudflare dashboard under "My Profile" > "API Tokens", create a token (Using the "Edit Cloudflare Workers" template is recommended) with the following configurations:

   • Your Account - Workers KV Storage:Edit, Workers Scripts:Edit, Account Settings:Read, Workers Tail:Read, Workers R2 Storage:Edit, Cloudflare Pages:Edit, Workers Builds Configuration:Edit, Workers Agents Configuration:Edit, Workers Observability:Edit, Containers:Edit, D1:Edit, AI Gateway:Read, AI Gateway:Edit, AI Gateway:Run, Cloudchamber:Edit, Browser Rendering:Edit
   • All zones - Workers Routes:Edit
   • All users - User Details:Read, Memberships:Read

   If using the Edit Cloudflare Workers template, make sure to add the missing permissions above manually.

   Important: Some features like D1 databases and R2 may require a paid Cloudflare plan.

With Custom Domain:

Enter your custom domain (or press Enter to skip): myapp.com
✅ Custom domain set: myapp.com
Use remote Cloudflare resources (KV, D1, R2, etc.)? (Y/n): 
Configure for production deployment? (Y/n): 

Without Custom Domain:

Enter your custom domain (or press Enter to skip): [press Enter]
⚠️  No custom domain provided.
   • Remote Cloudflare resources: Not available
   • Production deployment: Not available
   • Only local development will be configured

Continue with local-only setup? (Y/n): 

Cloudflare AI Gateway (Recommended)

• Automatic token setup: When selected, CLOUDFLARE_AI_GATEWAY_TOKEN is automatically set to your API token
• No manual configuration: The script handles all AI Gateway authentication
• Better performance: Caching, rate limiting, and monitoring included

Custom OpenAI URL (Alternative)

• For users with existing OpenAI-compatible endpoints
• Requires manual model configuration in worker/agents/inferutils/config.ts

The setup script offers multiple AI providers with intelligent multi-selection:

Available Providers:

1. OpenAI (for GPT models)
2. Anthropic (for Claude models)
3. Google AI Studio (for Gemini models) - Default & Recommended
4. Cerebras (for open source models)
5. OpenRouter (for various models)
6. Custom provider (for any other provider)

Provider Selection:

• Select multiple providers with comma-separated numbers (e.g., 1,2,3)
• Each selected provider will prompt for its API key
• Custom providers automatically generate PROVIDER_NAME_API_KEY variables
• Custom providers are automatically added to worker-configuration.d.ts

Google AI Studio (Recommended):

• Default model configurations use Gemini models
• No additional worker/agents/inferutils/config.ts editing required
• Best compatibility - This is the model used in the official deployment at https://build.cloudflare.dev
• You can get a free API key from https://aistudio.google.com/

Other Providers:

• Strong warning: You MUST edit worker/agents/inferutils/config.ts
• Change default model configurations from Gemini to your selected providers
• Model format: <provider-name>/<model-name> (e.g., openai/gpt-4, anthropic/claude-3.5-sonnet)
• Review fallback model configurations

Without AI Gateway:

• Manual config.ts editing required for all model configurations
• Model names must follow <provider-name>/<model-name> format

The script will also ask for OAuth credentials:

• Google OAuth: For user authentication and login (not AI Studio access)
• GitHub OAuth: For user authentication and login
• GitHub Export OAuth: For exporting generated apps to GitHub repositories (separate from login OAuth)

If you don't provide OAuth credentials, by default at login, you will only be able to use email-based registration/login.

You can let users sign in with their Cloudflare account. The same consent also connects their Cloudflare AI Gateway, so generations can run on their own credits ("Use my AI Gateway" toggle in settings).

1. Create an OAuth client

Create an OAuth client in the Cloudflare dashboard: https://dash.cloudflare.com/?to=/:account/oauth-clients

Configure these redirect URLs on the client (replace the origin with your deployment's URL; for local development this is http://localhost:5173):

• https://your-domain.com/api/auth/callback/cloudflare — "Login with Cloudflare"
• https://your-domain.com/auth/callback — connect AI Gateway (from settings)

Grant the client these scopes (Cloudflare uses dotted identifiers, not OIDC email/profile):

openid user-details.read ai.read ai.write aig.read aig.run aig.write offline_access

The scopes and the Cloudflare OAuth endpoint URLs are hardcoded in the worker (worker/services/oauth/cloudflare-connect.ts) and are not configurable — just make sure the OAuth client is authorized for all of these scopes, or the authorization request fails with invalid_scope.

2. Set the environment variables

Add the client credentials to .dev.vars (and .prod.vars for production):

CLOUDFLARE_OAUTH_CLIENT_ID="<your-oauth-client-id>"        # required for Login with Cloudflare
CLOUDFLARE_OAUTH_CLIENT_SECRET="<your-oauth-client-secret>"
CF_OAUTH_ENCRYPTION_KEY="<32-byte base64 key>"             # required for AI Gateway; encrypts the token cookie

Set ENABLE_CLOUDFLARE_LIMITS="true" in the Cloudflare dashboard for production, or in .dev.vars for local development.

The "Login with Cloudflare" button appears as soon as CLOUDFLARE_OAUTH_CLIENT_ID and CLOUDFLARE_OAUTH_CLIENT_SECRET are set — identity login needs nothing else.

The AI Gateway connect/auto-connect (running generations on the user's own credits) additionally requires the dashboard-managed ENABLE_CLOUDFLARE_LIMITS="true" and CF_OAUTH_ENCRYPTION_KEY (generate with openssl rand -base64 32). If the key is missing, the gateway feature is disabled (same as leaving ENABLE_CLOUDFLARE_LIMITS unset) and login simply skips the gateway auto-connect — users fall back to the free tier and can connect later.

Generated-app previews use the SPACE_DO and LOADER bindings. Add the ARTIFACTS binding for Artifacts-backed spaces. Docker is not required for the current Think/SpaceDO preview path. SandboxDockerfile and container setup remain only for legacy tooling.

Feature settings are intentionally omitted from the committed wrangler vars. For deployed environments, set them in the Cloudflare dashboard; keep_vars: true preserves their values when wrangler deploy runs. For local development, set them in .dev.vars. Do not add these settings back to wrangler.jsonc or wrangler.staging.jsonc.

Existing deployments retain previously configured dashboard values when this configuration is deployed. New deployments must explicitly set ENABLE_READ_REPLICAS="true" or ENABLE_CLOUDFLARE_LIMITS="true" in the dashboard to preserve the former committed defaults.

If you prefer to set up manually:

Copy .dev.vars.example to .dev.vars and fill in your values:

cp .dev.vars.example .dev.vars

# Essential
CLOUDFLARE_API_TOKEN="your-api-token"
CLOUDFLARE_ACCOUNT_ID="your-account-id"

# Security
JWT_SECRET="generated-secret"

# Domain (optional)
CUSTOM_DOMAIN="your-domain.com"

Create required resources in your Cloudflare account:

• KV Namespace for VibecoderStore
• D1 Database named vibesdk-db
• R2 Bucket named vibesdk-templates

Update resource IDs in wrangler.jsonc with the IDs from step 3.

After setup is complete:

# Set up database
bun run db:migrate:local

# Start development server
bun run dev

Visit your app at http://localhost:5173

Important Note: If you didn't specifiy any oauth credentials during setup, You would need to register an account for the first time.

D1 Database "Unauthorized" Error: This usually means:

• Your API token lacks "D1:Edit" permissions
• Your account doesn't have access to D1 (may require paid plan)
• You've exceeded your D1 database quota
• Solution: Update your API token permissions or upgrade your Cloudflare plan

Permission Errors: Ensure your API token has all required permissions listed above.

Domain Not Found: Make sure your domain is:

• Added to Cloudflare
• DNS is properly configured
• API token has zone permissions

Resource Creation Failed: Check that your account has:

• Available KV namespace quota (10 on free plan)
• D1 database quota (may require paid plan)
• R2 bucket quota (may require paid plan)
• Appropriate plan level for requested features

R2 Bucket "Unauthorized" Error: This usually means:

• Your API token lacks "R2:Edit" permissions
• Your account doesn't have access to R2 (may require paid plan)
• You've exceeded your R2 bucket quota
• Solution: Update your API token permissions or upgrade your Cloudflare plan

AI Configuration Issues:

• "AI Gateway token already configured" but token not in .dev.vars: Re-run setup, this was a bug that's now fixed
• Models not working with custom providers: Edit worker/agents/inferutils/config.ts to change default model configurations
• Custom provider not recognized: Check that the provider was added to worker-configuration.d.ts
• AI Gateway creation failed: Ensure your API token has AI Gateway permissions

Dynamic Worker Preview Issues:

• Confirm the SPACE_DO and LOADER bindings are configured; confirm ARTIFACTS only when ENABLE_ARTIFACTS="true".
• Check the branch deployment and signed preview URL.
• Use bun run dev:browser when local browser-console inspection is needed.

Deploy to Cloudflare Button Issues (Chat Interface):

• "Deploy button not working locally": Chat interface deploy button requires custom domain, initial deployment, and remote dispatch bindings
• "Dispatch namespace not found": Deploy your VibeSDK project to Cloudflare at least once first
• "Deploy fails with authentication error": Ensure your custom domain is properly configured and deployed
• Note: This refers to deploying generated apps from the chat interface, not GitHub repository deployments

Legacy Corporate Container Setup: The following certificate setup applies only when intentionally running legacy Docker-based tooling:

1. Copy your corporate root CA certificate to the project root (don't commit to git!)
2. Edit SandboxDockerfile to include your certificate:

# Add your company's Root CA certificate for corporate network access
COPY your-root-ca.pem /usr/local/share/ca-certificates/your-root-ca.crt
RUN update-ca-certificates

# Set SSL environment variables for cloudflared and other tools
ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/your-root-ca.crt
ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

⚠️ Security Warning: Never commit corporate CA certificates to public repositories. Use .gitignore to exclude certificate files and only use this for local development.

1. Check the setup report for specific issues and suggestions
2. Review the Cloudflare Workers documentation
3. Ensure all prerequisites are met

If you configured remote deployment during setup, you'll have a .prod.vars file ready for production. Deploy with:

bun run deploy

This will:

• Build the application
• Update Cloudflare resources
• Deploy to Cloudflare Workers
• Apply database migrations
• Configure custom domain routing (if specified)

If you only set up for local development initially, you can configure production later:

1. Run setup again and choose "yes" for remote deployment configuration
2. Provide production domain when prompted
3. Deploy using bun run deploy

Alternatively, create .prod.vars manually based on .dev.vars but with:

• Production domain in CUSTOM_DOMAIN
• Production API keys and secrets
• ENVIRONMENT="prod"

Once setup is complete:

1. Start developing with bun run dev
2. Visit http://localhost:5173 to access VibeSDK
3. Try generating your first AI-powered application
4. Deploy to production when ready with bun run deploy

The setup script creates and modifies these files:

vibesdk/
├── .dev.vars              # Local development environment variables
├── .prod.vars             # Production environment variables (if configured)
├── wrangler.jsonc         # Updated with resource IDs and domain
├── vite.config.ts         # Updated for remote/local bindings
├── migrations/            # Database migration files
└── templates/             # Template repository (downloaded)

The VibeSDK setup script provides a comprehensive, intelligent configuration experience:

• Simplified domain setup - One-time domain configuration with clear feature implications
• Intelligent AI provider selection - Multi-provider support with automatic configuration
• AI Gateway automation - Automatic token setup and configuration
• Custom provider support - Dynamic API key generation and worker configuration updates
• Production-ready - Both local development and production deployment configuration
• User-friendly defaults - Y/n prompts with clear default indicators

• Cloudflare resources (KV, D1, R2, AI Gateway, dispatch namespaces)
• Environment variables (.dev.vars and .prod.vars)
• Worker configuration (wrangler.jsonc, worker-configuration.d.ts)
• Database setup and migrations
• Template deployment
• ARM64 compatibility

The setup script handles everything from basic Cloudflare resource creation to advanced AI provider configuration, making it easy to get started regardless of your Cloudflare plan or AI provider preferences.

For any issues during setup, check the troubleshooting section above or refer to the comprehensive status report the script provides at the end.

USE_TUNNEL_FOR_PREVIEW, SandboxDockerfile, and container instance settings belong to the retired sandbox preview path. Current generated-app previews run as Dynamic Workers loaded by SpaceDO. Do not troubleshoot the current preview path as a Docker or cloudflared tunnel unless you are intentionally running legacy tooling.

The "Deploy to Cloudflare" button in the chat interface (for generated apps) has specific requirements for local development:

Note: This refers to the deployment button within the VibeSDK platform's chat interface, not the GitHub repository deploy button.

Requirements:

1. Custom domain must be properly configured during setup
2. Initial deployment - Project must be deployed at least once to your Cloudflare account
3. Remote dispatch bindings - wrangler.jsonc must have remote dispatch namespace enabled
4. Dispatch worker - A dispatch worker must be running in your account

Why These Requirements?

• The deploy feature uses Cloudflare's dispatch namespace system
• Dispatch requires a running worker in your account to handle deployment requests
• Local-only development isn't yet supported for this in vibesdk

Current Status: Making "Deploy to Cloudflare" work completely in local-only mode is not yet implemented.

For current previews, verify the SpaceDO Durable Object binding, Worker Loader binding, branch deployment, and signed preview URL. Verify the Artifacts namespace only when ENABLE_ARTIFACTS="true". Build failures originate in @cloudflare/worker-bundler; application runtime failures should be inspected through browser console logs. If an issue persists, open a GitHub issue with the setup report and deployment error.