A Bash Cheat Sheet: Adding a Model to Local watsonx Orchestrate

When working locally with IBM watsonx Orchestrate Development Edition, there is a recurring setup pattern I keep coming back to:

  • reset the environment
  • start the server
  • configure credentials
  • add a model

— and only then start experimenting.

To avoid repeating the same commands manually, I often use a small Bash automation script. Think of it as a cheat sheet for beginners and encoded as an easy executable workflow.

The GIF below shows an example usage:

1. Why this Script Exists

When I work with the local watsonx Orchestrate Development Edition I may need multiple times to do setups, and they tend to fail for boring reasons:

  • wrong virtual environment
  • forgotten environment variables
  • stale connections
  • models not registered correctly

This script makes the happy path explicit and repeatable. So, this is nothing magical — just disciplined automation.

2. What the Script Does (High-Level)

In one linear flow, the script:

  1. Activates the Python virtual environment
  2. Resets and starts the local Orchestrate server
  3. Loads environment variables from .env
  4. Activates the local Orchestrate environment
  5. Lists available models
  6. Configures a watsonx_credentials connection
  7. Adds a model backed by watsonx.ai
  8. Starts an interactive chat
  9. Tails relevant server logs

Colorized output is intentionally used — when something breaks, your eyes go there first.

3. The Bash Cheat Sheet

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW} Starting wxo_local_start.sh ${NC}"
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW} Activating virtual environment... ${NC}"
source venv/bin/activate
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW} Running watsonx Orchestrate server reset...${NC}"
orchestrate server reset
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW} Set environments variables...${NC}"
source .env
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW} Start local Orchestrate server using \`watsonx.ai\` for the models.${NC}"
orchestrate server start --env-file .env --with-connections-ui --with-doc-processing --accept-terms-and-conditions
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW} Activating local environment watsonx Orchestrate configuration ...${NC}"
orchestrate env activate local
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW} Listing available models ...${NC}"
orchestrate models list
echo -e "\n${BLUE}========================================${NC}"
cd adk-project/model-gateway/
export AGENTMODEL=${WXO_AGENT_MODEL}
echo "Model: ${AGENTMODEL}"
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW}  Create a connection ${NC}"
orchestrate connections remove --app-id watsonx_credentials
orchestrate connections add --app-id watsonx_credentials
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW}  Configure credentials for the connection ${NC}"
orchestrate connections configure --app-id watsonx_credentials --env draft --kind key_value --type team
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW}  Set the credenticals ${NC}"
orchestrate connections set-credentials --app-id watsonx_credentials --env draft --entries "api_key=${WATSONX_APIKEY}"
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW}  Add model ${NC}"
orchestrate models add --name ${AGENTMODEL} --app-id watsonx_credentials --provider-config  "{\"watsonx_space_id\": \"${WATSONX_SPACE_ID}\"}"
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW}  Start chat ${NC}"
orchestrate chat start
echo -e "\n${BLUE}========================================${NC}"
echo -e "${YELLOW}  Server logs ${NC}"
orchestrate server logs | grep "ai-gateway-1"

The example for the environment file.

## Local: https://developer.watson-orchestrate.ibm.com/developer_edition/wxOde_setup#myibm
export WO_DEVELOPER_EDITION_SOURCE=myibm
export WO_ENTITLEMENT_KEY=
export WATSONX_APIKEY=
export WATSONX_SPACE_ID=<Id of watsonx Orchestrate> 
export WXO_API_KEY=${WATSONX_APIKEY}
export WATSONX_REGION=us-south
export WATSONX_URL=https://${WATSONX_REGION}.ml.cloud.ibm.com
export ASSISTANT_LLM_API_BASE=https://${WATSONX_REGION}.ml.cloud.ibm.com
export ASSISTANT_EMBEDDINGS_API_BASE=https://${WATSONX_REGION}.ml.cloud.ibm.com
export ROUTING_LLM_API_BASE=https://${WATSONX_REGION}.ml.cloud.ibm.com
export ORCHESTRATE_API_TOKEN=blablub
export WXO_AGENT_MODEL=watsonx/openai/gpt-oss-120b

4. Additional Resources

If you want to go deeper or verify individual steps used in the script, the following resources are the most relevant starting points:

I hope this was useful to you and let’s see what’s next?

Greetings,

Thomas

#watsonx, #watsonxOrchestrate, #AgenticAI, #AIAgents, #LLMOps, #AIOrchestration, #BashAutomation, #LocalAI

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Blog at WordPress.com.

Up ↑