Skip to main content
You can install or uninstall watsonx Orchestrate Developer Edition using ADK CLI commands. To get started, make sure Docker Engine is installed and the .env file is properly configured.

​
Installation prerequisites

Before installing watsonx Orchestrate Developer Edition, make sure you meet the following requirements:
Your computer needs to meet the following requirements:
ComponentMinimumRecommended
CPU8-core8-core
RAM16 GB32 GB
You must have access to at least one of the following services:
  • watsonx Orchestrate
  • watsonx.ai
You need a valid license for watsonx Orchestrate Developer Edition. You can obtain a license by:
  • Purchasing a SaaS license for watsonx Orchestrate
  • Contacting IBM Sales for a direct purchase

​
Configuring container manager

You install and uninstall watsonx Orchestrate Developer Edition automatically using ADK CLI commands. Since the installation runs inside a Docker container, you need to have Docker Engine and Docker Compose installed on your machine. You can install Docker Engine and Docker Compose natively on systems that offer official support. Alternatively, for systems without native support, you can use container managers such as Rancher or Colima to install and configure them. Click the tabs below to learn how to install and configure Docker Engine and Docker Compose based on your operating system.
  • macOS
  • Windows
  • Linux
macOS doesn’t officially support Docker Engine or Docker Compose. To install and run them, use a container manager like Rancher or Colima.
  • To install Docker Engine and Docker Compose using Rancher, see see Rancher Desktop for macOS.
    If you use Apple Silicon hardware with Rancher Desktop, enable Rosetta support to use the Apple Virtualization (VZ) framework.
  • To install Docker Engine and Docker Compose using Colima, see Colima.
After you install Docker Engine and Docker Compose, open your terminal, Command Prompt (CMD), or PowerShell and run the docker and docker compose commands. These commands display a list of available options and subcommands that you can use to interact with Docker. The image below shows an example of the output returned by these commands.

​
Configuring .env file

The .env file is a plain text file that stores environment variables. The ADK uses the variables you define in this file to authenticate your user and install watsonx Orchestrate Developer Edition. The variables you need to configure depend on the authentication method you choose. You can authenticate using one of the following methods:
  • watsonx Orchestrate account Use this method if you have a watsonx Orchestrate account or if you’re using a 30-day trial.
  • myIBM Use this method if you purchased a watsonx Orchestrate Developer Edition license through sales or if you’re using an on-premises version.
  • Custom Image Registry Use this method if you’ve already copied the required Docker images to an image registry. For example, an Artifactory repository.
Click the tabs below to view instructions for configuring the .env file based on your authentication method.
  • watsonx Orchestrate account
  • myIBM
  • Custom Image Registry
To authenteticate using watsonx Orchestrate account:
1

Create a .env file

Create a file named .env.
2

Configure the .env file

Add the following variables to your .env file:
​
WO_DEVELOPER_EDITION_SOURCE
The source ID for the watsonx Orchestrate Developer Edition. Set orchestrate.
​
WO_INSTANCE
The watsonx Orchestrate service instance URL.To obtain the service instance URL, follow these steps:
  1. Log in to your watsonx Orchestrate account.
  2. Click your user profile and open the Settings page.
  3. Open the API details tab.
  4. Copy your service instance URL.
​
WO_API_KEY
The watsonx Orchestrate API key.To obtain the API key, follow these steps:
  1. Log in to your watsonx Orchestrate account.
  2. Click your user profile and open the Settings page.
  3. Open the API details tab.
  4. Click Generate API key.
    Your API key is unique and can’t be edited or deleted in the settings page. You must save the API key in a safe location.
If you’re using an on-premises setup, you also need to set the following environment variables:
​
DOCKER_IMAGE_PULL_LAYERS_PARALLELISM
Boolean environment variable that controls whether image layers are pulled in parallel. Defaults to true.Treated as false if DOCKER_IMAGE_PULL_PARALLEL_WORKERS_COUNT is set to 1.
​
DOCKER_IMAGE_PULL_PARALLEL_WORKERS_COUNT
Integer value that defines how many Docker image layers are pulled in parallel. Accepts values from 1 to 10.Values outside this range trigger a fallback to the default value. Defaults to 7.
​
USE_RANGE_REQUESTS_IN_DOCKER_IMAGE_PULLS
Boolean environment variable that enables ranged requests when pulling large layers. Defaults to true.
Note:Only takes effect when DOCKER_IMAGE_PULL_LAYERS_PARALLELISM is enabled.
​
WO_VERIFY_SSL
For on-premises (CPD) deployments, ADK uses SSL authentication by default to connect to a registry proxy in your watsonx Orchestrate on-premises environment. You can control this behavior by setting the WO_VERIFY_SSL environment variable. Use this variable to enable or disable SSL authentication.
  • Enable with the system SSL certificate
  • Enable with a custom SSL certificate
  • Disable SSL Security
To enable SSL security using the system’s default SSL certificate, set the WO_VERIFY_SSL environment variable to True:
.env
WO_VERIFY_SSL=True
Additionally, if you operate in a region other than us-south, configure the region variables. Set the following variables:
​
ASSISTANT_LLM_API_BASE
The assistant LMM API endpoint for your region
​
ASSISTANT_EMBEDDINGS_API_BASE
The assistant embedding API endpoint for your region.
​
ROUTING_LLM_API_BASE
The routing LLM API endpoint for your region.
​
WATSONX_URL
The watsonx endpoint for your region.

​
Optional: Configuring caching layers for on-premises

If you use a watsonx Orchestrate on-premises instance to pull images, you can configure caching layers to speed up Docker image downloads. This setup creates a cache in the ADK watsonx Orchestrate folder and stores all pulled layers. With caching enabled, each layer downloads only once during the cache period, which you control. You can reuse these layers whenever needed. All cached layers appear in the folder located at <home>/.cache/orchestrate. To configure caching layers, add the following environment variable to your .env file:
​
IGNORE_DOCKER_LAYER_CACHING
Boolean environment variable that determines whether CPD Docker image layers are cached in the local orchestrate cache during pulls. Defaults to false.
To clean up cached image layers, use the ADK CLI. For more information, see Cleaning on-premises cache layers.

​
Installing watsonx Orchestrate Developer Edition components

Use the orchestrate <component> start command to install watsonx Orchestrate Developer Edition components. Before you begin, ensure the following prerequisites are met: This command pulls the required images and creates Docker containers for the selected components. You can install the following:
Note:
  • If you encounter issues during installation, see the Troubleshooting section.
  • After pulling the images, you can set the WO_DEVELOPER_EDITION_SKIP_LOGIN environment variable to true to skip ICR login. The CLI uses existing images without downloading new ones.

​
Installing watsonx Orchestrate Developer Edition: watsonx Orchestrate server

The watsonx Orchestrate server runs locally on your machine. You can use it to gain more control when developing and debugging your agents. To install watsonx Orchestrate server, run:
BASH
orchestrate server start -e <path-.env-file>
Once installed, the following services become available:
Note: This command doesn’t start the local UI for watsonx Orchestrate. To start it, run orchestrate chat start. For more information, see Launching the local UI.
You can also use a custom docker-compose.yml file to install watsonx Orchestrate server. However, ADK does not officially support custom configurations. Make sure you understand the changes before proceeding. For more information, see Using custom watsonx Orchestrate Developer Edition docker file.

​
Installing watsonx Orchestrate Developer Edition: Orchestrate copilot server

The Orchestrate copilot server enables the copilot assistant, which helps you build agents and tools through the CLI chat. To install Orchestrate copilot server, run:
BASH
orchestrate copilot start --env-file <env_file>

​
Stopping watsonx Orchestrate Developer Edition components

Use the orchestrate <component> stop command to stop a watsonx Orchestrate Developer Edition components.
Note: After stopping a component, run the installation command again to restart it.

​
Stopping watsonx Orchestrate Developer Edition: watsonx Orchestrate server

To stop watsonx Orchestrate server, run:
BASH
orchestrate server stop

​
Stopping watsonx Orchestrate Developer Edition: Orchestrate copilot server

To stop Orchestrate copilot server, run:
BASH
orchestrate copilot stop

​
Uninstalling watsonx Orchestrate Developer Edition components

To uninstall all watsonx Orchestrate Developer Edition components, reset the server and then remove the containers using Docker.
1

Reset the server

Run the following command to reset the server:
BASH
orchestrate server reset
2

Delete all containers and volumes

Run the following command to remove all containers and volumes:
BASH
docker system prune -a --volumes

​
What’s Next?

After installing watsonx Orchestrate Developer Edition, you can use server commands in the ADK CLI to interact with the platform. For more details, see the ADK CLI documentation. You can also use the watsonx Orchestrate Developer Edition APIs to support agent development and testing. For more information, see watsonx Orchestrate Developer Edition APIs.