OpenParable
Skip to content
← Back to skills

Budibase Setup Run

Development
budibase-setup-run

Budibase Setup Run is an Agent Skill for development published in the Budibase/budibase repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Budibase/budibase/blob/HEAD/.agents/skills/budibase-setup-run/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/budibase-setup-run, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

  1. Install Yarn if needed:
npm install -g yarn
yarn -v
  1. Confirm Docker and Compose are available and running:
docker --version
docker compose version
docker info
  1. 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:

Services And Ports

Expect these local services:

ServicePortNotes
Nginx proxy10000Main entry point
Builder3000Vite/Svelte dev server
Server4001Koa API for apps
Worker4002Background jobs and platform APIs
MinIO4004S3-compatible storage
CouchDB4005Primary database
CouchDB SQS4006Queue-related CouchDB service
Redis6379Cache, sessions, queues
LiteLLM4000Optional 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.