budibase-setup-run

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.

1. Clone and enter the repo:

git clone https://github.com/Budibase/budibase.git
cd budibase

2. 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.

3. Install Yarn if needed:

npm install -g yarn
yarn -v

4. Confirm Docker and Compose are available and running:

docker --version
docker compose version
docker info

5. 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: [e-mail]
• 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.