Team development

The ADK team model is simple:

• One production bot, shared. The team commits agent.json and deploys to the same production bot.
• One development bot per person, private. Each teammate runs adk dev to create and reuse their own dev bot.
• Botpress Cloud is the source of truth. Integrations, configuration, tables, and knowledge live on each bot in Cloud, not in git.

This lets several people work on the same agent without overwriting each other’s local runtime or dev-bot integration setup.

What to commit

adk init scaffolds the right .gitignore for the team model.

Commit	Ignore
agent.json	agent.local.json
agent.config.ts	.adk/
src/	.env files
package.json and lockfiles	generated logs, traces, snapshots, and types

agent.json contains the shared production link. agent.local.json contains your private devId and any local overrides, so it stays out of git.

Start a new project

For a new project, create the agent and link it to a production bot:

adk init my-agent
cd my-agent
adk dev

adk init links the production bot through agent.json. The first adk dev creates your private development bot and records it in agent.local.json.

Join an existing project

For an existing team repo, clone it and create your own dev bot:

git clone <repo>
cd <repo>
bun install
adk login
adk dev

You inherit the team’s production bot from agent.json. Your dev bot starts as your own Cloud bot, so it does not automatically include every integration configured on production.

To seed your dev bot from production, copy dependency state:

adk integrations copy --from prod --to dev --dry-run
adk integrations copy --from prod --to dev --yes

Promote dependency changes

Build and test integrations on your dev bot first:

adk integrations add slack
adk integrations configure slack --set botToken=...
adk integrations status

When the dependency setup is ready, promote it to production:

adk integrations copy --from dev --to prod --dry-run
adk integrations copy --from dev --to prod --yes
adk deploy

copy moves integration and plugin state between bots. It does not move code, table rows, knowledge data, or conversations. Shipping code is adk deploy.

The source bot is never modified. The target bot is reconciled to match the source, so always review the dry run before using --yes, especially when the plan includes removals.

Move or hand off a project

Use export and import when you need a portable archive, a new workspace, or a handoff outside the current git repo:

adk export
adk export --no-config
adk import <archive>

adk export includes dependency config by default, and those values may include secrets. Use adk export --no-config when the recipient should not receive credentials or connection details.

adk import creates fresh bots unless you pass existing bot IDs. It does not deploy automatically.