| name | budibase-setup-run |
| description | Set up, bootstrap, run, and troubleshoot the Budibase monorepo for local development and automated VM environments. Use when an AI coding agent or developer needs to install prerequisites, clone Budibase, run yarn setup/build/dev/dev:agent, start or verify the local dev stack, log in locally, run package tests, or explain Budibase development ports and services. |
Budibase Setup Run
Core Path
Use this workflow for a fresh local Budibase checkout.
- Clone and enter the repo:
git clone https://github.com/Budibase/budibase.git
cd budibase
- Use the Node version pinned by the repo:
nvm install
nvm use
node -v
Budibase requires Node >=22.0.0 <23.0.0; this repo pins v22.18.0 in .nvmrc.
- Install Yarn if needed:
npm install -g yarn
yarn -v
- Confirm Docker and Compose are available and running:
docker --version
docker compose version
docker info
- Bootstrap and run the project for normal local development:
yarn setup
yarn setup configures submodules, checks Docker prerequisites, installs dependencies, builds packages, and starts the dev environment.
For automated VM environments where dependencies and build outputs can be cached, prefer the agent path:
yarn
yarn build
yarn dev:agent
yarn dev:agent preserves existing build artifacts by skipping the root clean/prebuild step. It also starts only the core Docker services and disables LiteLLM readiness checks for the dev process, which keeps startup lighter in constrained VM environments. Use it after a successful build or when restoring a VM image that already contains valid dist outputs.
Manual Setup
Use the manual path when yarn setup fails partway through or the user wants separate steps:
yarn
yarn build
yarn dev
On first setup, yarn build is required before the dev loop. Later edits to shared packages such as @budibase/shared-core, @budibase/backend-core, or types may require another build.
Running Locally
Start the local development environment from the repo root:
yarn dev
This command:
- Creates or updates
.env through scripts/dev/manage.js.
- Frees app ports through
yarn kill-all.
- Runs package prebuilds.
- Starts the server, worker, builder, and Docker-backed development stack.
For automated VM runs after a successful build, use:
yarn dev:agent
This keeps the normal developer workflow unchanged while reducing startup work and memory usage in cached environments.
Access Budibase at:
- Main proxy:
http://localhost:10000
- Builder:
http://localhost:10000/builder
Default local login:
- Email:
local@budibase.com
- Password:
cheekychuckles
Services And Ports
Expect these local services:
| Service | Port | Notes |
|---|
| Nginx proxy | 10000 | Main entry point |
| Builder | 3000 | Vite/Svelte dev server |
| Server | 4001 | Koa API for apps |
| Worker | 4002 | Background jobs and platform APIs |
| MinIO | 4004 | S3-compatible storage |
| CouchDB | 4005 | Primary database |
| CouchDB SQS | 4006 | Queue-related CouchDB service |
| Redis | 6379 | Cache, sessions, queues |
| LiteLLM | 4000 | Optional AI proxy, token budibase |
Health checks:
curl http://localhost:4001/health
curl http://localhost:4002/health
Common Commands
Build everything:
yarn build
Run type checks:
yarn check:types
Run lint:
yarn lint
Run a package test from inside that package:
cd packages/server
yarn test path/to/test-file.test.ts
Run only server and worker:
yarn dev:server
Run the optimized automated-environment startup path:
yarn dev:agent
Troubleshooting
If Docker commands fail, ensure Docker Desktop or the Docker daemon is running before rerunning setup.
If ports are stale, run:
yarn kill-all
If dependencies or build outputs look corrupt, rebuild without deleting Docker-backed data:
yarn restore
If the user is in a cloud VM with nested Docker, Docker may need to be started manually before yarn dev:
sudo dockerd
Do not change /var/run/docker.sock to be world-writable. If Docker permission errors persist, use the environment's approved Docker group, rootless Docker, or VM provisioning setup.
If local mode changes do not appear in the browser, clear Budibase cookies for localhost.
Contributor Notes
Use @budibase/ scoped imports between packages. The main package split is:
- Backend:
packages/server, packages/worker, packages/backend-core
- Frontend:
packages/builder, packages/frontend-core, packages/bbui
- Shared:
packages/shared-core
For server API tests, prefer TestConfiguration from packages/server/src/tests/TestConfiguration.ts. For automation tests, use createAutomationBuilder from packages/server/src/automations/tests/utilities/AutomationTestBuilder.ts.
