Botpress: the open-source monorepo behind Botpress Cloud agents

What botpress/botpress actually contains

The repository is a pnpm and Turbo monorepo, not a deployable chat server. The README lists four things inside it: integrations, devtools, example bots, and plugins. Integrations are the public and open-source connectors maintained by Botpress and by the community, published to the Botpress Hub. Devtools are three npm packages: @botpress/cli for building, deploying and managing bots, integrations and plugins, @botpress/client for type-safe access to the Botpress APIs, and @botpress/sdk, which is the SDK used to build integrations. The bots folder holds examples written only with the client, the SDK and the CLI. Plugins are marked "coming soon" in the README.

The audience follows from that layout. This is for developers who are already on Botpress Cloud and want to extend it: write an integration against a third-party API, publish it, then use it from a bot. It is also for developers who prefer code over a visual builder, since the bots folder shows how to drive the platform programmatically. The README is explicit that this is not the recommended way to build bots and is not a replacement for Botpress Studio.

The top-level entries confirm the shape: integrations/, packages/, bots/, plugins/, interfaces/ and a Dockerfile sit alongside workspace files such as pnpm-workspace.yaml and turbo.json. The Dockerfile builds from the monorepo root and targets specific integrations, for example docker build -f Dockerfile -t botpress-chat --target chat .

How an integration moves from template to Botpress Hub

The mechanism is a CLI-driven pipeline. You generate a project from a template, edit two files, then deploy. The README names those two files: integration.definition.ts holds the definition, and src/index.ts holds the implementation. The definition is what the platform reads to know the integration's shape; the implementation is the code that runs.

Deployment goes to a workspace, not to a public registry by default. According to the README, bp deploy pushes the current version to your workspace and makes it available to all your bots; if that version already exists it is updated, otherwise a new version is created. Visibility is a separate decision: integrations stay private to the workspace unless you pass --visibility public, which publishes to the Botpress Hub for every Botpress user. There is a one-way door here that the README states plainly: once a version of an integration is public, it cannot be updated again. That constraint shapes release discipline, because a mistake in a published version cannot be patched in place.

The Dockerfile adds a detail about how integrations are assembled. It copies packages, integrations, interfaces and patches into the build context, with a comment explaining that bp add resolves the bpDependencies of an integration from source, so the referenced interfaces must be present. Builds are then filtered, excluding @botpress/vai, @botpress/zai and llmz. The final stages copy a built .botpress/dist/index.cjs into small runtime images, with PORT set to 8081 and an entrypoint of node server.js. That is a per-integration packaging story, not a general hosting story.

Installing the Botpress CLI and deploying a first integration

Start with the CLI. The README gives three package-manager variants; the npm one is below. It installs @botpress/cli globally, which is what puts the bp command on your path.

npm install -g @botpress/cli

Next, create an integration. The README says to run this in any directory and any git repository of your choice, and that you do not have to fork the repository to create an integration. The command generates a project from one of the proposed templates, so expect to be asked which template you want.

bp init

You then edit integration.definition.ts for the definition and src/index.ts for the implementation. When you want to try it, deploy to your workspace. The README states this makes the integration available to all your bots, and that an existing version is updated while a new one is created otherwise.

bp deploy

Publishing is a separate flag. Only run this when you are ready to share the version with the community, because the README says a public version cannot be updated again.

bp deploy --visibility public

If you would rather build the monorepo from source, the README lists git, node and pnpm as prerequisites, with the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 called out for Windows. The documented sequence is clone, pnpm install, pnpm run build, pnpm run check.

The bots-as-code path is deliberately second class

The bots folder is the part most likely to be misread. It contains examples of bots made only with the client, the SDK and the CLI. The README's own framing is blunt: this is not the recommended way to build bots and is in no way a replacement for Botpress Studio. It justifies the folder as useful for experienced developers who want a more programmatic approach, and notes that the Botpress team uses the same primitives internally because the Studio and the SDK share them.

Treat that as a design statement rather than a limitation to work around. If your team expects a supported, first-class code-first workflow, the repository is telling you the visual Studio path is the intended one and the bots folder is an example set. Choosing the programmatic route means accepting that you are following examples rather than a documented product surface. The README does not describe a support policy, versioning guarantee or upgrade path for those examples.

There is a second boundary worth noting. This repository is for Botpress Cloud. The README redirects anyone with a problem related to on-premise Botpress v12 to the separate Botpress v12 repository. So a team looking for a self-hosted deployment of the current product will not find it here, and the Dockerfile's targets are built integration images, not the platform itself.

Release cadence versus repository activity

The release list is the clearest signal about where the product lives. The three most recent releases shown are v12.30.9 on 2023-06-22, v12.30.8 on 2023-04-24 and v12.30.7 on 2023-02-16. Those are v12 line releases, and the README already routes v12 users to a different repository. Meanwhile the last push to this repository was on 2026-09-09, roughly three years after the newest listed release. Nothing in the README explains that gap, and it does not document a release process for the Cloud packages.

That mismatch matters for planning. If you pin your work to a tagged release, the tags you can see are old and belong to a line the README treats as separate. If you instead consume @botpress/cli, @botpress/sdk and @botpress/client from npm, you are tracking whatever those packages publish, and the monorepo's own version numbers are not the contract. The repository is not archived, and the last push is recent, but the release metadata does not describe the Cloud tooling's versioning. Verify the npm package versions before you build a dependency policy around them.

For upgrades, the practical exposure is your integration. Because a public version cannot be updated again, you cannot silently patch a published integration; the README implies a new version is created when the current one is not already deployed. Plan for version churn on the Hub rather than in-place fixes.

Licence and the cost of contributing

Everything in the repository is MIT. The README states that all packages are open-source software under the MIT License, and that by contributing you agree to release your code under the same licence. For an integrator this is permissive: you can read the integration code, fork it, and ship your own version. There is no copyleft obligation described here, and no separate commercial licence mentioned for the repository contents. This is a description of what the README says, not legal advice; if your organisation has rules about contributing to third-party projects, read the LICENSE file and SECURITY.md in the repository root.

Contribution expectations are split by scope. The README welcomes pull requests and issues for code contained in the repository, and invites the community to contribute integrations or publish their own to the Botpress Hub. For bugs or features related to Botpress Cloud itself, it says you may open an issue here but that you will get a faster response on Discord. That is a real support-shape difference: repository issues are not the primary channel for platform problems.

The maintenance cost you take on is mostly your own integration code plus the CLI and SDK versions you depend on. The repository gives you pnpm run check as a combined gate covering sherif, dependency checks, formatting, linting and type checks, and pnpm run fix to apply the automatic parts. Those scripts are for working inside the monorepo.

Alternatives and when to look elsewhere

The obvious alternative is Botpress Studio, and it is not really a competitor: it is the same platform. The README says the Studio and the SDK use the same underlying primitives, and it calls the code-first bots folder a non-replacement for the Studio. The difference is the interface, not the runtime. If you want a visual builder with the platform's intended workflow, use Studio; if you want to define integrations and drive bots from TypeScript, use this repository. You can mix them, since integrations deployed to a workspace are available to all your bots.

A genuine alternative is a framework you host yourself, such as the LangChain-style tooling implied by this repository's own topic list. The difference in approach is where the runtime lives. Here, the runtime is Botpress Cloud: you deploy integrations into a workspace, and visibility is a Hub-level concept with an immutability rule for public versions. With a self-hosted framework, you own deployment, scaling and versioning, and you gain the ability to patch anything at any time. The trade is that you also own the chat channel plumbing, the studio-equivalent tooling and the Hub-style distribution that Botpress provides.

The repository's own README points v12 on-premise users to a different codebase, which is the clearest signal that this is not the self-hosting option. If self-hosting the current product is a hard requirement, this is the wrong repository.

Editorial conclusion

Adopt this repository if you want to write Botpress integrations in TypeScript or drive bots programmatically through the SDK and CLI. Do not adopt it if you need a self-hosted chatbot runtime: the README points on-premise v12 users to the separate Botpress v12 repository, and the bots folder is explicitly not the recommended way to build bots. Before committing, verify that your workspace is on Botpress Cloud, that your integration template exists in bp init, and that you accept that a public version cannot be updated again after bp deploy --visibility public.

Frequently asked questions

Official sources

1. botpress/botpress on GitHub
2. License: MIT
3. Project website
4. README
5. Releases