Installing watsonx Orchestrate Developer Edition

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:

Hardware requirements

Your computer needs to meet the following requirements:

Component	Minimum	Recommended
CPU	8-core	8-core
RAM	16 GB	32 GB

When running --with-doc-processing

Component	Minimum	Recommended
CPU	8-core	8-core
RAM	24 GB	32 GB

LLM Inference Provider

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

watsonx Orchestrate Developer Edition license

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.

watsonx Orchestrate account
myIBM
Custom Image Registry

To authenticate using a watsonx Orchestrate account:

Create a .env file

Create a file named .env.

Configure watsonx Orchestrate instance variables in the .env file

Add the following variables to your .env file:

The source ID for the watsonx Orchestrate Developer Edition. Set orchestrate.

The watsonx Orchestrate service instance URL.

Show more details

To obtain the service instance URL, follow these steps:

Log in to your watsonx Orchestrate account.
Click your user profile and open the Settings page.
Open the API details tab.
Copy your service instance URL.

The watsonx Orchestrate API key.

Show more details

To obtain the API key, follow these steps:

Log in to your watsonx Orchestrate account.
Click your user profile and open the Settings page.
Open the API details tab.
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.

.env Example

WO_DEVELOPER_EDITION_SOURCE=orchestrate
WO_INSTANCE=<service_instance_url>
WO_API_KEY=<wxo_api_key>

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.

The root user for the Minio object storage service.

The username for the Langfuse service used for observability and tracing.

The basic authentication username for the MCP Gateway service.

The username for the ClickHouse analytical database service.

The password for the PostgreSQL database used by the platform.

The root password for the Minio object storage service.

The password for the Langfuse service.

The basic authentication password for the MCP Gateway service.

The administrator password for the MCP Gateway service.

The password for the ClickHouse analytical database service.

The password for the Elasticsearch or OpenSearch service used for indexing and search.

The password for the Milvus vector database service.

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

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:

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.

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.

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.

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.

Boolean environment variable that determines whether CPD Docker image layers are cached in the local orchestrate cache during pulls. Defaults to false.

Show more details

Caching layers speed up Docker image downloads for on-premises instances. 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 clean up cached image layers, use the ADK CLI. For more information, see Cleaning on-premises cache layers.

.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

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:

The assistant LMM API endpoint for your region

The assistant embedding API endpoint for your region.

The routing LLM API endpoint for your region.

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/

To authenticate using myIBM:

Create a .env file

Create a file named .env.

Configure watsonx Orchestrate instance variables in the .env file

Add the following variables to your .env file:

The source ID for the watsonx Orchestrate Developer Edition. Set myibm.

An entitlement key from a valid watsonx.ai instance.

Show more details

To obtain the entitlement key, follow these steps:

Access My IBM.
Click View Library.
Click Add a new key +.
Copy the entitlement key.

A Groq instance. To get your API key, see Keys.

The API key of your instance. To get your API Key, see Managing API Keys.

A watsonx.ai instance on IBM Cloud. This instance is required to setting up the Deployment Space for the watsonx Orchestrate Developer Edition. If you don’t have one, create it and locate your space ID. You can create a new instance and get the space ID in the Developer access page on IBM Cloud.

.env Example

WO_DEVELOPER_EDITION_SOURCE=myibm
WO_ENTITLEMENT_KEY=<my_entitlement_key>
WATSONX_APIKEY=<my_watsonx_api_key>
WATSONX_SPACE_ID=<my_space_id>

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.

The root user for the Minio object storage service.

The username for the Langfuse service used for observability and tracing.

The basic authentication username for the MCP Gateway service.

The username for the ClickHouse analytical database service.

The password for the PostgreSQL database used by the platform.

The root password for the Minio object storage service.

The password for the Langfuse service.

The basic authentication password for the MCP Gateway service.

The administrator password for the MCP Gateway service.

The password for the ClickHouse analytical database service.

The password for the Elasticsearch or OpenSearch service used for indexing and search.

The password for the Milvus vector database service.

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

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:

The assistant LMM API endpoint for your region

The assistant embedding API endpoint for your region.

The routing LLM API endpoint for your region.

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/

To authenticate using a custom image registry:

Create a .env file

Create a file named .env.

Configure watsonx Orchestrate instance variables in the .env file

Add the following variables to your .env file:

The source ID for the watsonx Orchestrate Developer Edition. Set custom.

The URL of the image registry that hosts the watsonx Orchestrate Developer Edition images.

The username for authenticating with the image registry. Leave it blank to skip login.

The password for authenticating with the image registry. Leave it blank to skip login.

.env Example

WO_DEVELOPER_EDITION_SOURCE=custom
REGISTRY_URL=<registry_url>
REGISTRY_USERNAME=<registry_username>
REGISTRY_PASSWORD=<registry_password>

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.

The root user for the Minio object storage service.

The username for the Langfuse service used for observability and tracing.

The basic authentication username for the MCP Gateway service.

The username for the ClickHouse analytical database service.

The password for the PostgreSQL database used by the platform.

The root password for the Minio object storage service.

The password for the Langfuse service.

The basic authentication password for the MCP Gateway service.

The administrator password for the MCP Gateway service.

The password for the ClickHouse analytical database service.

The password for the Elasticsearch or OpenSearch service used for indexing and search.

The password for the Milvus vector database service.

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

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:

The assistant LMM API endpoint for your region

The assistant embedding API endpoint for your region.

The routing LLM API endpoint for your region.

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.

Show command flags

string

required

Path to your .env file.

boolean

Enable Langfuse support.

boolean

Enable IBM’s native observability framework.

boolean

Accept the terms and conditions shown in the logs when the server starts.

boolean

Provide the path to a custom docker-compose file to use instead of the default compose file.

boolean

Option to store secret values from the provided env file in the config file (~/.config/orchestrate/config.yaml).

boolean

Enable IBM Document Processing to extract information from business documents. This activates the Watson Document Understanding service.

boolean

Enables connections UI to facilitate OAuth connections and credential management via a UI.

boolean

Enable voice support.

boolean

Enable Langflow support. For more information about Langflow, see Authoring Langflow tools.

boolean

Enable support for AI assisted builder features. For more information about AI Builder, see AI Builder Overview.

string

The username you configure for watsonx Orchestrate Developer Edition services. If you do not provide a username, the system generates one by using your OS username. If that attempt fails, the system sets the name orchestrate. This applies to Langfuse, Minio, MCP Gateway, and ClickHouse. The username must contain at least three characters.

Note:For users who update from earlier versions to 2.6.0. If you have any server configured by an older version, whether it is running or stopped, your database uses the old default credentials because the database was created before the new configuration. You need to reset and start the environment to ensure the database container uses the newest credentials.If you want to keep your existing data after the update, you can override the service credentials for each service by configuring them in the .env file. For more information, see the related documentation section. For more information, see Configure services credentials for watsonx Orchestrate Developer Edition in the .env file.

string

The password you configure for watsonx Orchestrate Developer Edition services. If you do not provide a password, the system prompts you to enter one during the first setup. This applies to PostgreSQL, Langfuse, Minio, MCP Gateway, ElasticSearch, Milvus, and Clickhouse. The password must contain at least eighteen characters.

By default, the following features are disabled:

Agent Knowledge - Upload files
Agentic Workflow - Document Processing

To enable these features, you have two options:

Provide WO_INSTANCE and WO_API_KEY in your .env file. For more information, see Configuring .env file using watsonx Orchestrate account.
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:

OpenAPI Docs: http://localhost:4321/docs. This API documentation is also available in the watsonx Orchestrate Developer Edition APIs.
API Base URL: http://localhost:4321/api

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.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Installing watsonx Orchestrate Developer Edition

Installation prerequisites

Configuring .env file

Installing watsonx Orchestrate Developer Edition

Uninstalling watsonx Orchestrate Developer Edition

What’s Next?

​Installation prerequisites

​Configuring .env file

​Installing watsonx Orchestrate Developer Edition

​Uninstalling watsonx Orchestrate Developer Edition

​What’s Next?

Installation prerequisites

Configuring .env file

Installing watsonx Orchestrate Developer Edition

Uninstalling watsonx Orchestrate Developer Edition

What’s Next?