Contributing

This page is for people who change OpenBot itself. It shows how to set up your computer, run the server and the checks, and find your way in the code.

Set up

You need devenv. devenv gives you the exact tools for the project: Node.js, pnpm, PostgreSQL, mkcert, and more. You need Docker only to build and check the images. See Deploy. Run every command through devenv shell -- <command>, so you always use these tools.

Get the code

git clone <repository-url> openbot
cd openbot

Make local settings

devenv shell -- pnpm dev:setup
devenv shell -- mkcert -install

dev:setup makes .env.development with a new random secret key in OPENBOT_SECRET_KEYS. It also makes a local TLS certificate in .devenv/dev/. If your .env.development is from an older version, delete it and run dev:setup again. You can also reset the development database. See Configuration. mkcert -install makes your computer trust that certificate.

Start the development server

devenv shell -- pnpm dev

pnpm dev runs devenv up. It does these steps:

It starts PostgreSQL 18 on 127.0.0.1:5433, with the user openbot_dev. devenv runs it as a normal process. Its data lives in .devenv/state/postgres.
It installs the packages with pnpm install --frozen-lockfile.
It builds OpenBot and the packages it needs.
It runs the database migrations.
It starts the development server at https://localhost:8443. The server writes the platform settings for this origin itself, so there is no setup step.

When you change a file in packages/*/src, devenv starts OpenBot again.

The development server uses a local test account, test models, and a test App. No outside service is needed. To sign in and make a user token, see Quick start.

Checks

Command	What it does
`devenv shell -- pnpm install`	Installs all packages.
`devenv shell -- pnpm build`	Builds every package with tsdown.
`devenv shell -- pnpm typecheck`	Checks the types of every package.
`devenv shell -- pnpm -r test`	Runs the tests of every package.
`devenv shell -- pnpm --filter @openbot-build/core test`	Runs the tests of one package.
`devenv shell -- treefmt`	Formats the code with Prettier and nixfmt.

Run pnpm build before pnpm typecheck. Packages import each other from their built files.

Tests use Node.js’s own test runner. OpenBot tests start their own short-lived PostgreSQL server with the tools from devenv. They need no secrets and no outside services. GitHub Actions runs the same build, typecheck, and test commands. See Deploy.

Repository layout

Path	What it holds
`packages/`	The workspace packages. See Packages.
`packages/docs/`	This docs site.
`packages/template/`	A starting point for a new package. It is not part of the workspace.
`protocol-test/`	The public test service for the App Protocol. See Protocol test.
`deploy/`	Files to deploy OpenBot. Each target has its own folder. See Deploy.
`deploy/docker/`	The Dockerfile, the Bake file, Compose files, the production environment template, and the image checks.
`.env.development.example`	The template for `.env.development`.
`patches/`	Fixes for exact versions of outside packages.
`references/`	Source code of other open source projects, as Git submodules. Only for reading.
`devenv.nix`	The development tools, settings, and processes.

The references/ folder is not part of the build. To read that code, fetch it with git submodule update --init.

To start a new package, copy packages/template/ to packages/<name>/. Then change its name, entry point, and dependencies.

The docs site

The docs site is an Astro site built with Starlight. The build makes static files only. Start it with:

devenv shell -- pnpm --filter @openbot-build/docs dev

Then open http://localhost:4321.

Path in `packages/docs/`	What it is
`content/docs/*.mdx`	The pages. The file name is the URL: `deploy.mdx` is `/docs/deploy`.
`astro.config.ts`	The site settings and the order of the pages in the sidebar.
`src/components/`	The components that pages can use without an import: `Callout`, `Steps`, and more.
`src/pages/index.astro`	The home page.
`src/pages/openapi.json.ts`	Serves `openapi.json` at `/openapi.json`, so people can download it.
`scripts/api.ts`	Makes `openapi.json` from the API contract.

The API reference at /docs/api is made from openapi.json by the starlight-openapi plugin. Do not write it by hand. The script runs before every dev and build. When you change the API contract in @openbot-build/api, the reference changes too. When you add a group to the contract, give it a title and a description in scripts/api.ts. The script stops with an error until you do. The build also makes /llms.txt and /llms-full.txt, which give the docs as plain text for AI tools. To check that every page builds, run devenv shell -- pnpm --filter @openbot-build/docs build.

Each push to main publishes the site to openbot.build. See Publish the docs site.

Project rules

Simple English

Write all text in Simple English. This covers docs, code comments, error messages, logs, prompts, and test text. Use short sentences and common words. Explain each technical term the first time you use it.

Headless

OpenBot has no user interface. Do not add pages, front ends, or client apps to the repository. The docs site is the only exception. Every new feature starts as an operation in the @openbot-build/api contract. Then the server handles it. Every operation must work with a user token and with the sign-in cookie. It must also say which permission it needs, with a Required or GroupRequired annotation. See Permissions.

One current model

Do not keep old paths for old callers, old clients, or old data. When a contract or the storage must change, change it directly. The only exception is a small fix for a bug in an outside package or tool.

Effect data first

Use the immutable data types of Effect, such as HashMap, Chunk, and Option. Use the mutable types of JavaScript only when you really need them.

Small, real changes

Build what gives real value. Keep each change focused, and test the parts that can really break.

The full rules for contributors are in AGENTS.md at the root of the repository.

License

OpenBot uses the GNU Affero General Public License, version 3 only (AGPL-3.0-only). The full text is in the LICENSE file at the root of the repository. When you send a change, you agree that it uses the same license.