Skip to main content
Important:
  • If you installed watsonx Orchestrate Developer Edition before ADK version 2.0, remove all containers before upgrading. Run orchestrate server reset to clear them. The Developer Edition no longer depends on an external container engine. If you skip the reset, you create multiple installations that consume unnecessary system resources and cause port conflicts.
  • If you want to use watsonx Orchestrate Developer Edition on Windows and you already have Docker installed, remove it from your system before you continue. Then install watsonx Orchestrate Developer Edition directly on Windows and let the ADK installer create the Docker environment for you. You cannot install watsonx Orchestrate Developer Edition inside a Docker environment that you created on your own. The installation needs a clean environment to run without issues.
You can install or uninstall watsonx Orchestrate Developer Edition using ADK CLI commands. To get started make sure your .env file is properly configured. Use ADK CLI commands to install or uninstall watsonx Orchestrate Developer Edition. Before you start, configure the environment variables that give you access to your watsonx Orchestrate Developer Edition instance. Define these variables in an .env file.

​
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
When running --with-doc-processing
ComponentMinimumRecommended
CPU8-core8-core
RAM24 GB32 GB
You must have access to at least one of the following services:
  • watsonx Orchestrate on SaaS
  • watsonx.ai
  • Groq
  • A custom llm provider provisioned through the AI Gateway
You need a valid license for watsonx Orchestrate Developer Edition. You can obtain a license by:
  • Purchasing a SaaS license for watsonx Orchestrate on either IBM Cloud or AWS
  • Purchasing an On-premises license for watsonx Orchestrate. The myIBM option uses your entitlement key to watsonx Orchestrate.
  • Contacting IBM Sales for a direct purchase

​
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.
To authenticate using a watsonx Orchestrate account:
1

Create a .env file

Create a file named .env.
2

Configure watsonx Orchestrate instance variables in 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.
​
WO_API_KEY
The watsonx Orchestrate API key.
.env Example
WO_DEVELOPER_EDITION_SOURCE=orchestrate
WO_INSTANCE=<service_instance_url>
WO_API_KEY=<wxo_api_key>
3

Configure services credentials for watsonx Orchestrate Developer Edition in the .env file

watsonx Orchestrate Developer Edition uses several services. You configure their credentials manually in the .env file.
Note:If you already configured service credentials, setting these variables replaces your previous credentials when you start the server.
​
MINIO_ROOT_USER
The root user for the Minio object storage service.
​
LANGFUSE_USERNAME
The username for the Langfuse service used for observability and tracing.
​
MCP_GATEWAY_BASIC_USER
The basic authentication username for the MCP Gateway service.
​
CLICKHOUSE_USER
The username for the ClickHouse analytical database service.
​
POSTGRES_PASSWORD
The password for the PostgreSQL database used by the platform.
​
MINIO_ROOT_PASSWORD
The root password for the Minio object storage service.
​
LANGFUSE_PASSWORD
The password for the Langfuse service.
​
MCP_GATEWAY_BASIC_PASSWORD
The basic authentication password for the MCP Gateway service.
​
MCP_GATEWAY_ADMIN_PASSWORD
The administrator password for the MCP Gateway service.
​
CLICKHOUSE_PASSWORD
The password for the ClickHouse analytical database service.
​
ES_PASSWORD
The password for the Elasticsearch or OpenSearch service used for indexing and search.
​
MILVUS_PASSWORD
The password for the Milvus vector database service.
​
DB_ENCRYPTION_KEY
The encryption key you use to secure sensitive database fields.
.env Example
MINIO_ROOT_USER=minioadmin
LANGFUSE_USERNAME=orchestrate
MCP_GATEWAY_BASIC_USER=admin
CLICKHOUSE_USER=clickhouse

POSTGRES_PASSWORD=postgres
MINIO_ROOT_PASSWORD=watsonxorchestrate
LANGFUSE_PASSWORD=orchestrate
MCP_GATEWAY_BASIC_PASSWORD=MCPbasic
MCP_GATEWAY_ADMIN_PASSWORD=MCPadmin
CLICKHOUSE_PASSWORD=clickhouse
ES_PASSWORD=Elasticsearch
MILVUS_PASSWORD=Milvus
DB_ENCRYPTION_KEY=db_encryption_key
4

For on-premises: Configure on-premises variables in the .env file

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
ADK uses SSL authentication by default to connect to a registry proxy in your watsonx Orchestrate on-premises environment. Use this variable to enable or disable SSL authentication. Possible values:
  • True: To enable SSL security using the system’s default SSL certificate.
  • False: To disable SSL authentication.
  • SSL file path: To use a custom SSL certificate.
​
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.
.env Example
DOCKER_IMAGE_PULL_LAYERS_PARALLELISM=true
DOCKER_IMAGE_PULL_PARALLEL_WORKERS_COUNT=7
USE_RANGE_REQUESTS_IN_DOCKER_IMAGE_PULLS=true
WO_VERIFY_SSL=True
IGNORE_DOCKER_LAYER_CACHING=false
5

For regions other than us-south: Configure region variables in the .env file

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.
.env Example
ASSISTANT_LLM_API_BASE=https://<region-code>.ml.cloud.ibm.com/
ASSISTANT_EMBEDDINGS_API_BASE=https://<region-code>.ml.cloud.ibm.com/
ROUTING_LLM_API_BASE=https://<region-code>.ml.cloud.ibm.com/
WATSONX_URL=https://<region-code>.ml.cloud.ibm.com/

​
Installing watsonx Orchestrate Developer Edition

Once you have configured the environment variables in your .env file, install the watsonx Orchestrate server by running:
BASH
orchestrate server start -e <path-.env-file>
Use additional flags to enable optional services such as Langfuse by adding with-langfuse.
By default, the following features are disabled:
  • Agent Knowledge - Upload files
  • Agentic Workflow - Document Processing
To enable these features, you have two options:
  1. Provide WO_INSTANCE and WO_API_KEY in your .env file. For more information, see Configuring .env file using watsonx Orchestrate account.
  2. Run the orchestrate server start -e <path-.env-file> --with-doc-processing command. This command starts the server with document processing enabled. Make sure you allocate at least 24 GB of memory to your server for stable operation.
Once installed, the following services become available:
Note: Installing watsonx Orchestrate Developer Edition starts only the server, not the UI. To start the UI, run orchestrate chat start. For more information, see Starting watsonx Orchestrate Developer Edition UI.
In addition, you can install watsonx Orchestrate Developer Edition by using a custom docker-compose file or a custom image repository. For more information, see Using custom watsonx Orchestrate Developer Edition docker file and Creating custom Developer Edition image registry.

​
Uninstalling watsonx Orchestrate Developer Edition

If you no longer want to use watsonx Orchestrate Developer Edition, remove it and all its data from your computer. To do this, run:
BASH
orchestrate server purge

​
What’s Next?

After installing watsonx Orchestrate Developer Edition, you can use it as a local server with the orchestrate env activate local command. You can also start the watsonx Orchestrate UI. In addition, you can manage watsonx Orchestrate Developer Edition with the ADK CLI. For more information, see Managing Developer Edition.