for developers
Builder Desktop offers three execution modes, each designed for different development scenarios. This guide helps you understand each option and choose the right environment for your projects.
Your execution environment determines where and how your Fusion projects run:
- Cloud containers: Projects run on Builder.io's managed infrastructure
- Local machine: Projects run directly on your computer without containers
- Local containers: Projects run in isolated Docker or Podman containers on your machine
Run projects in managed cloud infrastructure—the same environment used by Builder.io's web application.
When to use:
- Quick testing without local setup
- Matching production-like environments
- You prefer not to run projects locally
- Team members have varying local machine capabilities
How it works:
- Builder Desktop connects to Builder.io's cloud infrastructure.
- Projects run in managed containers on Builder.io servers.
- The Desktop app streams logs and communications with the remote container.
- All processing happens in the cloud.
Run projects directly on your computer without containerization. Builder Desktop creates a temporary workspace and executes your development server natively.
When to use:
- Maximum performance and fastest startup times
- Direct access to local tools and services
- Standardized development environments across your team
- Projects requiring specific local configurations
- You prefer working directly on your host machine
How it works:
- Builder Desktop creates a workspace at
{userDataDir}/temp-workspaces/{projectId}/{branch}. - Clones your repository and any additional folders.
- Runs setup commands, such as
npm install, directly on your machine. - Starts your dev server using the configured development server command.
- Monitors the process and streams logs to the Builder Desktop interface.
Requirements:
- Node.js and npm (configure version in project settings)
- Git
- Project-specific dependencies installed locally
Run projects in isolated Podmanor Docker containers on your local machine. This mode provides consistent, reproducible environment while keeping everything running locally.
When to use:
- Teams requiring consistent environments across machines
- Projects with complex dependency requirements
- Testing with specific Node versions or OS configurations
- Organizations that need environment isolation
- Projects requiring specific OS packages or tools
How it works:
1. Builder Desktop uses Podman, or Docker-compatible engine, to create containers.
2. Selects appropriate base image based on your Node.js version and CPU architecture:
- ARM64:
docker.io/builderio/fusion-base-arm64:node<version> - x86_64:
docker.io/builderio/fusion-base:node<version>
3. Mounts your project workspace at /app inside the container.
4. Runs npx @builder.io/dev-tools launch with your project configuration.
5. Proxies the dev server through port mapping to localhost.
6. Streams container logs to Builder Desktop interface.
Requirements:
- Podman or Docker installed
- Sufficient system resources
- Container engine properly configured (Desktop handles Podman machine setup on macOS/Windows)
Enterprise customers can build and deploy custom Docker images to create standardized environments for their organization.
- Pre-install frequently used tools and packages
- Pin specific versions of dependencies
- Add OS-level packages your projects need
- Create standardized environments for your organization
Example custom Dockerfile:
FROM docker.io/builderio/fusion-base-arm64:node22
# Add custom OS packages
RUN apt-get update && apt-get install -y git jq postgresql-client
# Install global tools your team uses
RUN npm i -g turbo pnpm@8
# Optional: pin dev-tools version
RUN npm i -g @builder.io/dev-tools@latestSetup:
- Build your custom image.
- Push to GitHub Container Registry (GHCR).
- Configure the image path in Project Settings under Docker Image Path.
- For private images, provide GHCR authentication credentials.
Space administrators can set the default execution environment for all team members:
- Go to Space Settings → Desktop App Settings.
- Click the Edit button.
- Select the default execution environment.
Team members can override the Space-level setting:
- In the Builder Desktop app, press
Cmd/Ctrl + kto open the Command Palette. - Select Toggle Developer Options.
- Go to Settings → Advanced Settings → Labs.
- Select your preferred execution environment.
- Restart any active projects for changes to take effect.
The video below shows going to Settings to override the execution environment.
Some settings affect how projects run in different environments:
| Setting | Applies to | Purpose |
|---|---|---|
Node.js version | Local containers | Determines base image to use |
Memory limit | Local and cloud containers | Sets container resource constraints |
Docker image path | Local containers | Overrides default base image |
Environment variables | All environments | Available in local machine, local containers, and cloud |
Dev server port | All environments | Used as fallback when auto-detect is disabled |
Choose cloud containers if:
- You want the fastest setup without local configuration.
- Your team has varying local machine capabilities.
- You're doing quick testing or prototyping.
Choose local machine if:
- Performance is your top priority.
- You need direct access to local services, such as databases, and APIs.
- Your team has standardized development environments.
Choose local containers if:
- You need consistent environments across different machines.
- Your project has complex dependencies.
- You want environment isolation from your host machine.
- You're using custom Docker images (Enterprise).
Learn about Projects editing modes for building applications in Projects Design, Interact, and Code modes.
After installation, configure your preferred execution environment:
- Open Builder Desktop.
- Press
Cmd/Ctrl + Kto open the Command Palette. - Select Toggle Developer Options.
- In the section labeled Fusion Project Execution Environment (Developer Override), select your preferred execution environment.