Project setup

Building with the ADK works the same whether you’re solo or on a team:

Even solo, your project is ready for teammates from day one.

For the vocabulary behind profiles, targets, project links, and console modes, see ADK concepts. For the full multi-developer workflow, see Team development.

The project link

A linked project records which bots it talks to in two files:

File	Committed to git?	Holds
agent.json	Yes	The production link: bot ID, workspace ID, API URL
agent.local.json	No (gitignored)	Your development bot ID, plus any local overrides

Your development bot ID lives in agent.local.json, never in agent.json. Keeping it out of the shared file means each person’s dev bot stays private and you avoid merge conflicts.

When both files define the same link field, agent.local.json wins for that developer. This lets one person override the project locally without changing the shared production link.

Link a project to a production bot with adk link:

adk link                                # interactive: pick workspace, then bot
adk link --workspace <id> --bot <id>    # non-interactive

adk link connects to a production bot and writes agent.json. adk init runs it for you when you scaffold a project.

Development and production targets

Most commands act on one bot. The target decides which:

dev   →  your development bot
prod  →  the shared production bot

Command	Target	Notes
adk dev	dev	Runs your agent locally against your dev bot
adk chat	dev	Talks to a running adk dev
adk deploy	prod	Ships code and config to the production bot
adk kb sync --dev / --prod	dev or prod	One of --dev / --prod is required
adk integrations …	--target flag	Defaults to dev

The target chooses the bot. In normal projects, dev and prod both live in the same Botpress Cloud workspace.

In the Dev Console, the selector in the top-right switches the target you’re viewing between development and production:

Creating your development bot

adk init and adk link wire up the production bot only. Your development bot doesn’t exist until the first time you run adk dev, which creates one in Cloud and records its ID in agent.local.json so the same bot is reused next time.

If that dev bot is later deleted in Cloud, run adk dev again. The ADK clears the stale local ID and provisions a fresh development bot.

Working as a team

The team model comes down to one thing: what gets committed and what doesn’t. adk init sets up the right .gitignore for you.

Commit (shared)	Ignore (per-person or generated)
agent.json (the production link)	agent.local.json (your dev bot + overrides)
agent.config.ts, src/, package.json	.adk/ (generated types, logs, snapshots)
	.env files

Because integration state lives on each bot in Cloud rather than in git, each person’s dev-bot integrations are their own, and only the production bot’s are shared.

To join an existing project, clone it and start your own dev bot:

git clone <repo> && cd <repo>
bun install
adk login        # sign in with your own credentials
adk dev          # creates your personal development bot

You inherit the shared agent.json, so you’re pointed at the team’s production bot right away. Your dev bot starts empty. To copy the production bot’s integration setup onto it, see Managing dependencies.

Moving a project

To move a project to a different machine or workspace, export it to a portable archive and import it elsewhere:

adk export                # bundle source, config, and dependency setup into a .adk archive
adk export --no-config    # exclude integration config (omit anything that may be a secret)
adk import <archive>      # unpack into a new directory and create fresh bots

Local identity stays out of exported archives, and adk import never deploys automatically. Dependency config is included by default and can contain secret-like values, so use adk export --no-config when the recipient should not receive credentials or connection details.

Validate your project

Run adk check to validate a project without starting the dev server:

adk check

It verifies your Node.js version, runtime version, project structure, and generated types. The same checks run automatically during adk dev and adk deploy.