ADK concepts

Most ADK setup issues come from mixing together three separate ideas: who the CLI acts as, which bot a command touches, and where the Dev Console is pointed.

Quick map

Term	What it means
Profile	Your named login. It stores a token and API URL in ~/.adk/credentials and decides who the CLI acts as. Profiles are per-person and never committed.
Project link	The bot connection stored in agent.json and agent.local.json. It decides which workspace and bot IDs project commands use.
Target	dev or prod. The target chooses the bot: your private development bot or the shared production bot.
Production bot	The shared bot stored in agent.json. adk deploy ships code and config to this bot.
Development bot	Your private bot stored as devId in agent.local.json. adk dev creates it the first time you run locally.
Local runtime	The process started by adk dev. Your code runs on your machine, but bot state still lives in Botpress Cloud.
Dev Console	The browser UI opened by adk dev, adk dashboard, or adk. It can run in Local mode or Cloud mode.
Integration Hub	The Dev Console area for installing and configuring integrations and plugins. Its actions write directly to the targeted Cloud bot.
Dependency snapshot	The generated cache in .adk/dependencies/dev.json and .adk/dependencies/prod.json. It mirrors Cloud state, is gitignored, and should not be edited by hand.
Workspace	The Botpress Cloud workspace that owns your bots.

Three rules

1. Your profile supplies credentials. It does not decide which bot a project command touches.
2. Your project link supplies bot IDs. agent.json holds the shared production bot, and agent.local.json holds your private dev bot plus local overrides.
3. The target chooses the bot. dev and prod are two bots in Botpress Cloud. “Cloud” is not a third target.

How the pieces combine

When you run a project command, the ADK combines:

selected profile      project link                 command target
----------------      --------------------------   --------------
token            +    apiUrl                  +    dev  -> devId
profile apiUrl        workspaceId                  prod -> botId
                      botId
                      local devId

That means adk deploy --profile work uses the credentials from the work profile, but still deploys to the production bot recorded by the project. To change the bot, relink the project or use a local project override. To change the account, switch profiles.

For the file-level model, see Project setup. For credentials, see Profiles.