Repository: Budibase/budibase

Stars: 27828

CLAUDE.md

Budibase Agent Guide

Architecture

- Workspace uses Lerna monorepo with packages in packages/
- Main packages: server, worker, backend-core, frontend-core, client, builder, shared-core, bbui
- Use @budibase/ scoped imports between packages
- Backend packages (NodeJS): server, worker, backend-core
- Frontend packages (browser): builder, frontend-core, bbui
- Shared (NodeJS and browser): shared-core

Build/Test Commands

- Build: yarn build
- Lint: yarn lint (check) or yarn lint:fix (fix)
- Test: yarn test <filename> run inside of a packages/\* directory
- Type check: yarn check:types
- packages/server tests: if you're working on a test that uses the
datasourceDescribe function, that means you can pass DATASOURCE= as an env
var to the test to narrow it down to one specific database. The database strings
you can use can be found on DatabaseName in packages/server/src/integrations/tests/utils/index.ts

Code Style

- No semicolons, double quotes, 2-space tabs (see .prettierrc.json)
- Use TypeScript strict mode with consistent-type-imports
- Imports: Group external imports first, then internal @budibase/* packages
- Variables: camelCase, prefix unused with _
- Functions: Prefer arrow functions, use async/await over Promises
- Error handling: Use try/catch
- Types: Use interface for objects, type for unions/primitives, do NOT cast to any.
- Do not add backwards compatibility paths or broad "handle every scenario" logic unless explicitly instructed to do so for the task.
- Testing: Jest framework, use describe/it structure, mock external services
using nock.
- Only comment when it's really necessary to explain an unclear behaviour.
- Never use console.log in tests, the output will not be visible in STDOUT
when you run the tests. It is a waste of time.
- In application code use console.log instead of pino the logging framework.
We have made it so that console.log statements are redirected to pino.
- When you're writing tests, you don't need to assert or do conditional checks
on intermediate states. Just assert the final outcome
against, provided there are no type errors.
- Avoid adding nested ternary statements.

Test style - packages/server

- When building automations utilise the createAutomationBuilder function
found in packages/server/src/automations/tests/utilities/AutomationTestBuilder.ts
- When building tables, datasources, queries and various other Budibase resources check for functions like basicTable
found in packages/server/src/tests/utilities/structures.ts - use these to create a basic table, you can provide
extended configuration if required through the extra prop.
- Use TestConfiguration in packages/server/src/tests/TestConfiguration.ts for every API test case -
this can be used to access the test API under new TestConfiguration().api, a list of functions and
request/response types can be found in packages/server/src/tests/utilities/api.

Git

Never auto-commit changes unless explicitly asked to do so. You may ask permission to commit.

Never auto-push changes unless explicitly asked to do so. You may ask permission to push.

Pull requests

- Always respect the format of pull_request_template.md. Some sections may not
be required, you are free to ignore them. Don't add new sections, though.
- When you open a pull request, always open it as a draft so that it can be
reviewed by a human.
- Before opening a pull request, always make sure that the branch you're pushing
is up to date with master.
- If you're working on a bug, the name of the PR should start with the bug ID
in square brackets, e.g. [BUDI-1234]. The link to the bug should go into the
"Addresses" section of pull_request_template.md.

Browser use

- If you're browsing the Budibase product in a browser, you can find
comprehensive documentation at https://docs.budibase.com
- The local URL for the development server is http://localhost:10000. Before
running yarn dev, check to see if the development server is already running.
- The default login for local development is email "[email protected]" and
password "cheekychuckles".
- The product is split up by app, so to find things like data sources and
automations you must first make sure to select an app.

LiteLLM

- The LiteLLM API is available when in local development at localhost:4000
- The auth token is budibase

Misc

- When creating or switching branches, make sure the branch is up to date with
the remote on GitHub. Don't work on old code.

Cursor Cloud specific instructions

Services overview

| Service | Port | Notes |
| ------------------------ | ----- | -------------------------------------------------------------- |
| Nginx proxy (main entry) | 10000 | Routes to builder, server, worker, CouchDB, MinIO |
| Builder (Vite/Svelte) | 3000 | Frontend dev server |
| Server (Koa) | 4001 | Backend API for apps |
| Worker | 4002 | Background jobs; note .env sets WORKER_PORT=4002, not 4003 |
| CouchDB | 4005 | Primary database |
| CouchDB SQS | 4006 | |
| Redis | 6379 | Cache, sessions, queues |
| MinIO | 4004 | S3-compatible object storage |
| LiteLLM (optional) | 4000 | AI proxy; see ## LiteLLM section above for auth token |

Starting the dev environment

1. Docker must be running before yarn dev. The dev stack (CouchDB, Redis, MinIO, Nginx, optionally LiteLLM) is started automatically by yarn dev via packages/server/scripts/dev/manage.js.
2. yarn dev runs: dev:init (generates .env), kill-all (frees ports), prebuild, then starts server + worker + builder via lerna run --stream dev.
3. The worker listens on port 4002 (set by WORKER_PORT in .env), not 4003. Health check: curl http://localhost:4002/health.
4. Server health check: curl http://localhost:4001/health.
5. Full app is accessible at http://localhost:10000 via the Nginx proxy.

Running tests

- Run package-specific tests from inside the package directory: cd packages/<pkg> && yarn test <filename>.
- packages/server and packages/backend-core tests use scripts/test.sh wrappers around Jest.
- shared-core and string-templates tests run directly via jest.

Docker in Cloud VM

Docker is installed and configured with fuse-overlayfs storage driver and iptables-legacy for the nested container environment. The Docker daemon must be started with sudo dockerd before use. Socket permissions are set via chmod 666 /var/run/docker.sock so docker commands work without sudo.

Gotchas

- lerna is a devDependency and not globally installed. The yarn dev script works because yarn resolves local bins, but if running lerna directly, use npx lerna or yarn lerna.
- The postinstall hook runs husky install for git hooks. Pre-push hook requires git-lfs.
- Build is required before yarn dev for the first time: yarn build. Subsequent runs use nodemon for hot-reload of server/worker, but changes to shared packages (types, shared-core, backend-core) may require a rebuild.

README.md

<a href="https://www.budibase.com">
<img alt="Budibase" src="https://res.cloudinary.com/daog6scxm/image/upload/v1696515725/Branding/Assets/Symbol/RGB/Full%20Colour/Budibase_Symbol_RGB_FullColour_cbqvha_1_z5cwq2.svg" width="60" />
</a>

<h1 align="center">
Budibase
</h1>
<h3 align="center">
AI Agents that run your operations
</h3>

Budibase is an open-source operations platform that saves engineers 100s of hours building Agents, Apps and Automations, securely.

<h3 align="center">
<a href="https://account.budibase.app/register">Get started - we host (Budibase Cloud)</a>
 · 
<a href="https://docs.budibase.com/docs/hosting-methods">Get started - you host (Docker, K8s, DO)</a>
 · 
<a href="https://docs.budibase.com/docs">Docs</a>
 · 
<a href="https://github.com/Budibase/budibase/discussions?discussions_q=category%3AIdeas">Feature request</a>
 · 
<a href="https://github.com/Budibase/budibase/issues">Report a bug</a>
 · 
Support: <a href="https://github.com/Budibase/budibase/discussions">Discussions</a>
</h3>

✨ Features

Run your operations on one platform

Handle requests, automate workflows, manage processes, and connect your business systems - without stitching together multiple tools.

Employees ask questions, request approvals, and report issues every day. Budibase agents understand these requests and handle the work automatically.

Operations your team can run with AI agents

Employees ask questions, request approvals, and report issues every day. Budibase agents understand these requests and handle the work automatically.

Agents that take action

Budibase agents don’t just answer questions. They run workflows across your business - creating records, routing approvals, updating apps, and notifying teams automatically.

Connect the tools your business runs on

Integrate with databases, AI models, and business apps so agents and automations can take action across your operations.

Deploy with confidence and security

Budibase is open-source and is made to scale. With Budibase, you can self-host on your own infrastructure and globally manage users, onboarding, SMTP, apps, groups, theming and more. You can also provide users/groups with a portal and disseminate user management to the group manager.

---

Budibase Public API

As with anything that we build in Budibase, our public API is simple to use, flexible, and introduces new extensibility. To summarize, the Budibase API enables:

- Budibase as a backend
- Interoperability

#### Docs

You can learn more about the Budibase API at the following places:

- General documentation: Learn how to get your API key, how to use spec, and how to use Postman
- Interactive API documentation : Learn how to interact with the API

🏁 Get started

Deploy Budibase using Docker, Kubernetes, and Digital Ocean on your existing infrastructure. Or use Budibase Cloud if you don't need to self-host and would like to get started quickly.

Get started with self-hosting Budibase

- Docker - single ARM compatible image
- Docker Compose
- Kubernetes
- Digital Ocean
- Portainer

Get started with Budibase Cloud

🎓 Learning Budibase

The Budibase documentation lives here.

💬 Community

If you have a question or would like to talk with other Budibase users and join our community, please hop over to Github discussions

❗ Code of conduct

Budibase is dedicated to providing everyone a welcoming, diverse, and harassment-free experience. We expect everyone in the Budibase community to abide by our Code of Conduct. Please read it.

🙌 Contributing to Budibase

From opening a bug report to creating a pull request: every contribution is appreciated and welcomed. If you're planning to implement a new feature or change the API, please create an issue first. This way, we can ensure your work is not in vain.
Environment setup instructions are available here.

Not Sure Where to Start?

A good place to start contributing is by looking for the good first issue tag.

How the repository is organized

Budibase is a monorepo managed by lerna. Lerna manages the building and publishing of the budibase packages. At a high level, here are the packages that make up Budibase.

- packages/builder - contains code for the budibase builder client-side svelte application.

- packages/client - A module that runs in the browser responsible for reading JSON definition and creating living, breathing web apps from it.

- packages/server - The budibase server. This Koa app is responsible for serving the JS for the builder and budibase apps, as well as providing the API for interaction with the database and file system.

For more information, see CONTRIBUTING.md

📝 License

Budibase is open-source, licensed as GPL v3. The client and component libraries are licensed as MPL - so the apps you build can be licensed however you like. Budibase paid features are licensed under the Business Source License,

⭐ Stargazers over time

![Stargazers over time](https://starchart.cc/Budibase/budibase)

If you are having issues between updates of the builder, please use the guide here to clear down your environment.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Made with contrib.rocks.

Repository: Budibase/budibase

Stars: 27828

CLAUDE.md Copy Chapter

Budibase Agent Guide

Architecture Copy Chapter

Build/Test Commands Copy Chapter

Code Style Copy Chapter

Test style - packages/server Copy Chapter

Git Copy Chapter

Pull requests Copy Chapter

Browser use Copy Chapter

LiteLLM Copy Chapter

Misc Copy Chapter

Cursor Cloud specific instructions Copy Chapter

Services overview Copy Section

Starting the dev environment Copy Section

Running tests Copy Section

Docker in Cloud VM Copy Section

Gotchas Copy Section

README.md Copy Chapter

✨ Features Copy Chapter

Run your operations on one platform Copy Section

Operations your team can run with AI agents Copy Section

Agents that take action Copy Section

Connect the tools your business runs on Copy Section

Deploy with confidence and security Copy Section

Budibase Public API Copy Chapter

🏁 Get started Copy Chapter

Get started with self-hosting Budibase Get started with self-hosting Budibase')" title="Copy section prompt for LLMs"> Copy Section

Get started with Budibase Cloud Get started with Budibase Cloud')" title="Copy section prompt for LLMs"> Copy Section

🎓 Learning Budibase Copy Chapter

💬 Community Copy Chapter

❗ Code of conduct Copy Chapter

🙌 Contributing to Budibase Copy Chapter

Not Sure Where to Start? Copy Section

How the repository is organized Copy Section

📝 License Copy Chapter

⭐ Stargazers over time Copy Chapter

Contributors ✨ Copy Chapter