Botpress: a CLI and SDK for building LLM agents on Botpress Cloud

What the botpress/botpress repository actually ships

The name invites a wrong assumption. This is not the code you run to host a chatbot. The README lists four things: public integrations maintained by Botpress, devtools (CLI, SDK, API client), example bots written with the SDK and CLI, and plugins marked coming soon. The runtime lives behind app.botpress.cloud, and the tooling in this repository talks to it.

The audience follows from that split. Integration authors who want their connector listed on the Botpress Hub, developers who prefer TypeScript files in a git repository over a visual editor, and teams that need to script deployment are the people this repository serves. If you want a process you can install on your own hardware, the README sends you elsewhere: problems with on-premise Botpress v12 belong in the botpress/v12 repository, which is a different codebase. That sentence is the most useful boundary in the whole document, and it is easy to skim past.

How the CLI, SDK and Cloud fit together

An integration has two halves. The definition lives in integration.definition.ts and the behaviour lives in src/index.ts. The definition is what the workspace and the Hub see; the implementation is the code that runs when a bot invokes the integration. The CLI is the bridge: bp init scaffolds the pair from a template, bp deploy pushes the current version to your workspace.

Deployment has a versioning rule worth reading twice. Deploying a version that already exists updates it; deploying a new version creates one. Visibility is private by default, scoped to the workspace. bp deploy --visibility public publishes to the Botpress Hub, and after that the README states a published version cannot be updated again. So the public action is effectively one-way per version, and the practical pattern is to iterate privately and publish only a version you are willing to freeze.

The bots folder works differently. Those examples use the client, SDK and CLI directly, without the Studio. The README says the Studio and the SDK share the same underlying primitives, which is why the Botpress team uses this path internally. That is a statement about internal usage, not a recommendation for yours.

Getting an integration running: the commands the README gives

Install the CLI globally with npm, yarn or pnpm:

npm install -g @botpress/cli

Then create a project anywhere. The README notes this can be any directory and any git repository, and that you do not have to fork botpress/botpress. Run bp init and pick a template. Edit integration.definition.ts and src/index.ts. Deploy with bp deploy, and when the integration is ready for other users, bp deploy --visibility public.

Working on the repository itself is a separate flow. The prerequisites are git, node and pnpm, plus the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 on Windows. Then:

git clone https://github.com/botpress/botpress.git cd botpress pnpm install pnpm run build pnpm run check

The devtools table names three packages: @botpress/cli for building, deploying and managing bots, integrations and plugins; @botpress/client for type-safe clients against the Botpress APIs; @botpress/sdk for building integrations. The README leaves the docs and code links for the client and SDK rows empty, so the only documentation pointer it gives for those two is the general docs site.

Where the repository is thin, and where it is the wrong tool

The plugins section says coming soon. That is a promise, not a feature, and anyone planning around plugins should treat the folder as absent until it appears.

Release history is the sharper signal. The three most recent releases listed are v12.30.9 (June 2023), v12.30.8 (April 2023) and v12.30.7 (February 2023). Those are v12 tags, and v12 is the on-premise line that the README points at a different repository. Meanwhile the repository itself was pushed in September 2026. The honest reading is that the tags do not describe the Cloud tooling in this tree, and the material here does not explain how the npm packages are versioned or released. If your adoption decision depends on a release cadence you can audit, this repository does not give you one.

The wrong tool case is concrete. If you need to run the agent runtime yourself, on your own infrastructure, under your own operational control, nothing in this README describes that. The Cloud workspace is the deployment target, and the on-premise path is explicitly a different repository. A second case: if your team wants a visual builder, the Studio is the product, and the README describes bots-as-code as useful mainly for experienced developers who want to work programmatically.

How this differs from running a framework in your own process

The contrast worth drawing is with agent frameworks you install as a library and execute in your own Node process, wiring your own HTTP server, scheduler and state store. There, the deployment unit is your application and the model calls happen inside your runtime. Here, the deployment unit is an integration or bot definition uploaded to a workspace, and the execution surface belongs to Botpress Cloud. You write TypeScript either way; what changes is who operates the process, who holds the credentials, and where the logs live.

That difference decides most architecture questions. A framework in your process lets you place the agent next to your database and call internal services directly, at the cost of owning scaling, secrets and uptime. The Botpress path gives you a workspace, a Hub for distribution and a versioning model for publishing, at the cost of the runtime being remote and the integration boundary being defined by integration.definition.ts. Neither is strictly better. The repository is a poor fit for anyone whose requirement is that the agent process never leaves their network, and a reasonable fit for anyone whose requirement is distribution to other Botpress users.

Licence and the cost of keeping current

Every package in the repository is MIT licensed, and the README states that contributions are released under the same licence. MIT is permissive: you can use, modify and redistribute the code, including in closed products, provided the licence and copyright notice travel with it. That covers the packages in this tree. It does not automatically describe the hosted Cloud service, and the README does not discuss service terms, so do not read the repository licence as a statement about the platform. This is a description of what the file says, not legal advice.

The maintenance cost has two parts. First, the CLI is installed globally, so upgrades are a deliberate act (npm install -g @botpress/cli) rather than something a lockfile pins for you; there is no versioning or compatibility guidance in the material, so pinning and testing against your workspace is the only verifiable approach. Second, published integration versions are immutable. A bug in a public version cannot be patched in place; you ship a new version and ask users to move. That turns release hygiene into an ongoing obligation rather than a one-time task.

Editorial conclusion

Adopt this repository if your agents run on Botpress Cloud and you want integrations, bots or tooling as versioned TypeScript in your own git repo; the README states you do not need to fork it to create an integration. Do not adopt it if you need a self-hosted runtime, since the README redirects on-premise v12 users to the separate botpress/v12 repository, and do not treat the bots folder as the main authoring path, because the README calls it not recommended and not a replacement for Botpress Studio. Verify two things before committing: whether the pinned @botpress/cli version in your lockfile still matches the Cloud API you deploy against, and whether the public release cadence (v12.30.9 in June 2023) reflects the packages you actually install from npm.

Official sources

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