Installation and Setup

With example agents

Kodosumi consists of three main building blocks:

1. The Ray cluster to execute agentic services at scale.

2. The Kodosumi web interface and API services.

3. Agentic Services delivered through Kodosumi and executed through Ray.

Prerequisites

Python v.3.12

Ray v.2.44.1

Installation and setup guide

1

Create a project folder and activate a venv

Create a proect folder, name it the way you like

mkdir my-kodo-project
cd ./my-kodo-project

Create and activate a virtual environment, make sure you use the path to the python version you would like to use within this venv.

/opt/homebrew/bin/python3.12 -m venv venv
source venv/bin/activate

2

Install Kodosumi

There are 2 ways of installing Kodosumi.

Option 1: Using pip.

pip install kodosumi

Option 2: In case you want to install the latest version possible, pull the source code from Github, using dev branch (might be less stable).

git clone https://github.com/masumi-network/kodosumi.git
cd kodosumi
git checkout dev
pip install .
cd ..

3

Create service home (a directory for your agentic apps).

In this step you will create a directory ./home. This directory will host agentic services. Each agentic service runs in a custom environment which matches the specific service requirements.

Now, if you are just starting with Kodosumi, use the example apps from repo that we prepared for you.

If you didn't clone Kodosumi repo in the previous steps, now is a good time to do it in case you would like to deploy an example app provided in the repo.

git clone https://github.com/masumi-network/kodosumi.git

Directory ./kodosumi/apps contains various example services. Copy or link the cloned directory from ./kodosumi/apps to ./home/apps.

mkdir ./home
cp -r ./kodosumi/apps/hymn ./home/

4

Configure the environment

Based on deployment configuration in ./home/hymn/config.yaml Ray will create a dedicated Python environment for the service.

In config.yaml you define the Python package requirements and environment variables.

For this example, edit ./home/hmyn/config.yaml and add your OpenAI OPEN_API_KEY.

For this example we will deploy the hymn creating agent. Copy the example env variables to the app and enter your OPENAI_API_KEY .

applications:
- name: hymn
  route_prefix: /hymn
  import_path: hymn.app:fast_app
  runtime_env: 
    pip:
    - crewai
    - crewai_tools
    env_vars:
      OTEL_SDK_DISABLED: "true"
      OPENAI_API_KEY: add your key here      

5

Start Ray as a daemon

Change to ./home and start Ray inside this directory so Ray can import from this directory.

cd home 
ray start --head

Check Ray status with ray status and visit ray dashboard at http://localhost:8265. For additional info, check out Ray Documentation.

6

Deploy the app with Ray

Deploy example hymn.app in folder ./home. Use Ray serve deploy to launch the service in your localhost Ray cluster.

Ensure you start serve in the same directory as Ray (./home).

serve deploy ./hymn/config.yaml

This will setup a dedicated environment with Python dependencies crewai and crewai_tools. Ray sets up this environment based on the relevant sections in ./home/hymn/config.yaml.

Please be patient if the Ray serve applications take a while to setup, install and deploy. Follow the deployment process with the Ray dashboard at http://localhost:8265/#/serve.

In our experience initial deployment takes three to four minutes.

7

Start Kodosumi

Finally start the kodosumi components and register ray endpoints available at http://localhost:8001/-/routes.

The port is defined in config.yaml. The path /-/routes reports available endpoints of active Ray deployments.

Ensure you start and serve from the same directory as Ray (./home).

koco start --register http://localhost:8001/-/routes

This command starts kodosumi spooler in the background and kodosumi panel and API in the foreground.

Command koco start starts the kodosumi spooler and the kodosumi panel API and is equivalent to:

koco spool
koco serve

8

Look around

• Visit Kodosumi admin panel at http://localhost:3370.

• The default user is defined in config.py as name=admin and password=admin. Feel free to change it as you wish.

• If one or more Ray serve applications are not yet available when Kodosumi starts, you need to refresh the list of registered flows. Visit control screen in the admin panel and click RECONNECT.

• Launch the Hymn Creator from the service screen and revisit results at the timeline screen.

• See also the OpenAPI documentation with Swagger http://localhost:3370/schema/swagger.

9

Stop Everything

When you are done, stop the kodosumi services and spooler by hitting CNTRL+C in the corresponding terminal.

The spooler continues to run as a background daemon. You can stop the spooler with:

koco spool --status

Stop Ray serve with:

serve shutdown --yes

Stop the ray daemon:

ray stop