The watsonx Orchestrate Developer Edition enables you to have a local development environment of watsonx Orchestrate running on your computer. You can use the watsonx Orchestrate ADK to automatically install the watsonx Orchestrate Developer Edition.

The watsonx Orchestrate Developer Edition runs under a Docker container, and can’t be used to host a full working version of watsonx Orchestrate. The server runs under the host machine’s localhost, and can’t be used to provide remote access. Deploying the watsonx Orchestrate Developer Edition in a virtual machine is also not supported.

​
Installation prerequisites

  • Your computer needs to meet the following requirements:

    ComponentMinimumRecommended
    CPU8-core8-core
    RAM16 GB32 GB

  • Install Docker and Docker Compose engine. It is containerization engine used to install the watsonx Orchestrate Developer Edition. For more information, see Docker and Docker compose.

    • For Windows users, to install Docker and Docker Compose engine, you should also install the Windows Subsystem for Linux (WSL). For more information, see Windows Subsystem for Linux.

    Note:

    • To ensure better integration and performance, install the ADK inside your WSL environment, as your server will be running there. Once installed, you can build and manage your agents directly within WSL for a smoother development experience.
    • WSL 2 with Ubuntu distribution is recommended.
    • Install Docker Compose v2. The ADK is not compatible with Compose v1.

  • Install the ADK. For more information, see Installing the ADK.

  • You must have access to at least one of these services:

    • watsonx Orchestrate
    • watsonx.ai

    You can use at least one of these services to get access to the watsonx Orchestrate Developer Edition images.

​
Setup the environment

The watsonx Orchestrate Developer Edition is distributed as a Docker image. In order to pull the images from Docker, you must configure an environment file with the appropriate data.

​
Getting the entitlement key for watsonx.ai

You can download the images if you have a valid instance of watsonx.ai. In order to do that, you must obtain an entitlement key to proceed. To get the entitlement key, follow these steps:

  1. Access My IBM.

  2. Click View Library.

  3. Click Add a new key +.

  4. Copy the entitlement key.

​
Using your watsonx.ai account

  1. Create a watsonx.ai instance on IBM Cloud, if you do not have one already, and locate your space ID. You can create a new instance and get the space ID in the Developer access page on IBM Cloud.

  2. To get your API Key, see Managing API Keys.

  3. Create a .env file with the following contents:

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

    Replace <my_entitlement_key>, <my_watsonx_api_key>, and <my_space_id> with the appropriate information.

​
Using your watsonx Orchestrate account

Starting at version 1.5.0, you can now use your watsonx Orchestrate account to pull images from Docker, and you no longer need an entitlement key to pull the images.

  1. Log in to your watsonx Orchestrate account.

  2. Click your user profile and open the Settings page.

  3. Open the API details tab and 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.

  4. Copy your Service Instance URL:

    https://api.<region>.watson-orchestrate.ibm.com/instances/<wxo_instance_id>

  5. Create a .env file with the following contents:

    [.env]
    WO_DEVELOPER_EDITION_SOURCE=orchestrate
WO_INSTANCE=<service_instance_url>
WO_API_KEY=<wxo_api_key>

    Replace <service_instance_url>, <wxo_api_key>, <your_wxo_email>, and <your_wxo_password> with the appropriate information.

If you are unable to pull images using this method, you can still use the myibm value for WO_DEVELOPER_EDITION_SOURCE, and use the same WO_INSTANCE and WO_API_KEY in the .env file. However, you will need an entitlement key to download the images, which you can get by following the Getting the entitlement key for watsonx.ai procedure.

[.env]
WO_DEVELOPER_EDITION_SOURCE=myibm
WO_ENTITLEMENT_KEY=<my_entitlement_key>
WO_INSTANCE=<service_instance_url>
WO_API_KEY=<wxo_api_key>

​
Installing the watsonx Orchestrate Developer Edition with ADK

To install the watsonx Orchestrate Developer Edition with the ADK, run the following command in the CLI:

[BASH]
orchestrate server start --env-file={{The path of your .env file}}

Important:

To run this command, you need to accept all the Watsonx Orchestrate Developer Edition with ADK terms and conditions. For more information, see License reference.

To accept all terms and conditions, type “I accept”.

This will start a local server instance that you can connect to using the CLI. You can then use the CLI to manage your agents and tools just as you would for a production watsonx Orchestrate service instance.

The server start command is used to download and run the services that compose the watsonx Orchestrate service.

Once your server is installed, you can use it as a local environment to manage your agents and tools locally. To activate the local environment, use the command:

[BASH]
orchestrate env activate local