# 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 "local@budibase.com" 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

<p align="center">
  <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>
</p>
<h1 align="center">
  Budibase
</h1>
<h3 align="center">
  AI Agents that run your operations
</h3>
<p align="center">
  Budibase is an open-source operations platform that saves engineers 100s of hours building Agents, Apps and Automations, securely.
</p>

<h3 align="center">
 🤖 🎨 🚀
</h3>
<br>

<p align="center">
  <img alt="Budibase agent ui" src="https://res.cloudinary.com/daog6scxm/image/upload/v1775572268/github/Agent_preview.jpg">
</p>

<p align="center">
  <a href="https://github.com/Budibase/budibase/releases">
    <img alt="GitHub all releases" src="https://img.shields.io/github/downloads/Budibase/budibase/total">
  </a>
  <a href="https://github.com/Budibase/budibase/releases">
    <img alt="GitHub release (latest by date)" src="https://img.shields.io/github/v/release/Budibase/budibase">
  </a>
  <a href="https://twitter.com/intent/follow?screen_name=budibase">
    <img src="https://img.shields.io/twitter/follow/budibase?style=social" alt="Follow @budibase" />
  </a>
  <img src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg" alt="Code of conduct" />
  <a href="https://codecov.io/gh/Budibase/budibase">
    <img src="https://codecov.io/gh/Budibase/budibase/graph/badge.svg?token=E8W2ZFXQOH"/>
  </a>
</p>

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

<br /><br />

## ✨ 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.

<br /><br />

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

<p align="center">
  <img alt="Budibase chat deploy" src="https://res.cloudinary.com/daog6scxm/image/upload/v1775573887/github/Agent_Chat.jpg">
</p>

<br /><br />

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

<p align="center">
  <img alt="Budibase agent actions" src="https://res.cloudinary.com/daog6scxm/image/upload/v1775572270/github/Agent_Actions.jpg">
</p>
<br /><br />

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

<br />

---

<br />

## 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](https://docs.budibase.com/docs/public-api): Learn how to get your API key, how to use spec, and how to use Postman
- [Interactive API documentation](https://docs.budibase.com/reference/appcreate) : Learn how to interact with the API

<br /><br />

## 🏁 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](https://docs.budibase.com/docs/hosting-methods)

- [Docker - single ARM compatible image](https://docs.budibase.com/docs/docker)
- [Docker Compose](https://docs.budibase.com/docs/docker-compose)
- [Kubernetes](https://docs.budibase.com/docs/kubernetes-k8s)
- [Digital Ocean](https://docs.budibase.com/docs/digitalocean)
- [Portainer](https://docs.budibase.com/docs/portainer)

### [Get started with Budibase Cloud](https://budibase.com)

<br /><br />

## 🎓 Learning Budibase

The Budibase documentation [lives here](https://docs.budibase.com/docs).
<br />

<br /><br />

## 💬 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](https://github.com/Budibase/budibase/discussions)

<br /><br /><br />

## ❗ 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**](https://github.com/Budibase/budibase/blob/HEAD/docs/CODE_OF_CONDUCT.md). Please read it.
<br />

<br /><br />

## 🙌 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](https://github.com/Budibase/budibase/tree/HEAD/docs/CONTRIBUTING.md).

### Not Sure Where to Start?

A good place to start contributing is by looking for the [good first issue](https://github.com/Budibase/budibase/labels/good%20first%20issue) 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](https://github.com/Budibase/budibase/tree/HEAD/packages/builder) - contains code for the budibase builder client-side svelte application.

- [packages/client](https://github.com/Budibase/budibase/tree/HEAD/packages/client) - A module that runs in the browser responsible for reading JSON definition and creating living, breathing web apps from it.

- [packages/server](https://github.com/Budibase/budibase/tree/HEAD/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](https://github.com/Budibase/budibase/blob/HEAD/docs/CONTRIBUTING.md)

<br /><br />

## 📝 License

Budibase is open-source, licensed as [GPL v3](https://www.gnu.org/licenses/gpl-3.0.en.html). The client and component libraries are licensed as [MPL](https://directory.fsf.org/wiki/License:MPL-2.0) - so the apps you build can be licensed however you like. Budibase paid features are licensed under the [Business Source License](https://github.com/Budibase/budibase/blob/master/packages/pro/license.md),

<br /><br />

## ⭐ Stargazers over time

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

If you are having issues between updates of the builder, please use the guide [here](https://github.com/Budibase/budibase/blob/HEAD/docs/CONTRIBUTING.md#troubleshooting) to clear down your environment.

<br /><br />

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<a href="https://github.com/Budibase/budibase/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=Budibase/budibase" />
</a>

Made with [contrib.rocks](https://contrib.rocks).