Installing watsonx Orchestrate Developer Edition

If you have previously installed watsonx Orchestrate Developer edition before ADK version 2.0, first remove all containers by running orchestrate server reset before upgrading. watsonx Orchestrate Developer edition no longer has a dependency on on an external container engine. Failing to reset before upgrading can result in multiple installations of the application consuming unnecessary system resources and will result in port conflicts.

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.

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.

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 a 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:

WO_DEVELOPER_EDITION_SOURCE

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

WO_INSTANCE

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.

WO_API_KEY

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>

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.

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:

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/

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:

WO_DEVELOPER_EDITION_SOURCE

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

WO_ENTITLEMENT_KEY

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.

GROQ_API_KEY

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

WATSONX_APIKEY

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

WATSONX_SPACE_ID

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>

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/

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:

WO_DEVELOPER_EDITION_SOURCE

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

REGISTRY_URL

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

REGISTRY_USERNAME

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

WATSONX_SPACE_ID

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>

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 the environment variable configured in one .env file. To install watsonx Orchestrate server, run:

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

Flag	Type	Required	Description
`--env-file` (`-e`)	string	yes	Path to your `.env` file.
`--with-langfuse` (`-l`)	-	no	Enable Langfuse support.
`--with-ibm-telemetry` (`-i`)	-	no	Enable IBM’s native observability framework.
`--accept-terms-and-conditions`	-	no	Accept the terms and conditions shown in the logs when the server starts.
`--compose-file` (`-f`)	-	no	Provide the path to a custom docker-compose file to use instead of the default compose file.
`--persist-env-secrets` (`-p`)	-	no	Option to store secret values from the provided env file in the config file (`~/.config/orchestrate/config.yaml`).
`--with-doc-processing` (`-d`)	-	no	Enable IBM Document Processing to extract information from business documents. This activates the Watson Document Understanding service.
`--with-connections-ui (-c)`	-	no	Enables connections UI to facilitate OAuth connections and credential management via a UI.
`--with-voice` (`-v`)	-	no	Enable voice support.
`--with-langflow`	-	no	Enable Langflow support. For more information about Langflow, see Authoring Langflow tools.
`--with-ai-builder`	-	no	Enable support for AI assisted builder features. For more information about AI Builder, see AI Builder Overview.

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

Analyze

watsonx Orchestrate Developer Edition

watsonx Orchestrate MCP Server

Reference

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?

Release Notes

Get Started

Build

Analyze

watsonx Orchestrate Developer Edition

watsonx Orchestrate MCP Server

Reference

Legal notices

​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?