BOSS Object Starter Service (BOSS)
BOSS is a service that instantiates Python objects as HEROs based on a JSON configuration. The configuration can be read from a file, a URL (e.g. from a CouchDB), or from an environment variable. Essentially, BOSS allows you to quickly wrap your arbitrary Python object as a HERO and to run it.
📖 Below is a quick walkthrough of the basic functionalities. You find the full documentation here.
As an example, let's take an object available in the Python standard library, the FTP class from the ftplib module. To make BOSS create an object of the class FTP, we need the following configuration:
{
"_id": "test-json-ftp",
"classname": "ftplib.FTP",
"arguments": {
"host": "ftp.us.debian.org"
}
}
python -m boss.starter -u file:///absolute/path/to/ftp.json
Now our object is available in the default realm of our HEROS network. It can be viewed with any HEROObserver. For a graphical view, use HERO-Monitor.
Exposing the BOSS instance itself
To expose the BOSS instance as a HERO, use the --expose command line flag:
python -m boss.starter --expose -u file:///absolute/path/to/ftp.json
When the BOSS instance is exposed, HEROs can be dynamically added and removed by the calling the
add_hero(config: dict) and remove_hero(name: str) methods. This allows to run BOSS without any initial
configuration and manage the running HEROs from a remote service.
By default, the instance receives a unique name consisting of the hostname and a UUID. To change the name, use the --name argument:
python -m boss.starter --expose --name my_test_boss -u file:///absolute/path/to/ftp.json
Using the asyncio main loop
BOSS starts a asyncio loop that the started objects can use. If your object expects to get the loop object in the constructor you can define attach it to the boss loop through the magic string "@_boss_loop" as in the following example:
{
"_id": "statemachine",
"classname": "herostools.actor.statemachine.HERODatasourceStateMachine",
"arguments": {
"loop": "@_boss_loop",
"http_port": 9090,
"bind_address": "localhost",
"labels": {"system": "heros"}
}
}
Docker
A convenient way to deploy BOSS is inside of a Docker container. You can find pre-built containers images in our Docker registry.
You can also build the BOSS Docker image yourself from the Dockerfile in the repository:
docker build -t atomiq/boss .
A BOSS Docker service can be started with the following compose file
version: '2'
services:
httpclient:
image: registry.gitlab.com/atomiq-project/boss:latest
restart: always
network_mode: host
environment:
- |
BOSS1=
{
"_id": "docker-env-ftp",
"classname": "ftplib.FTP",
"arguments": {
"host": "ftp.us.debian.org"
}
}
command: python -m boss.starter -e BOSS1
Additionally, also specifying a file or URL is possible, such that (mounted) JSON files in the Docker container or web
URLs can be used as configuration sources. Note that the -e and -u options can be specified multiple times to define several objects that should be instantiated by the BOSS.
Metadata
Release files for heros-boss 2026.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| heros_boss-2026.0.2.tar.gz | 294.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| heros_boss-2026.0.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 317.4 kB
Release files / heros_boss-2026.0.2.tar.gz
| Download URL | heros_boss-2026.0.2.tar.gz |
|---|---|
| Size | 294.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a085e7cd13363a1395bce607a1a2bdbeb0f371991b14bddbf0a16d09bcfd6c4a
|
|
BLAKE2b-256 checksum How to use checksums |
3441c621e9ac3c26b25164aea1a42679171aabda5b1bf3ca345ea3be6dc935c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / heros_boss-2026.0.2-py3-none-any.whl
| Download URL | heros_boss-2026.0.2-py3-none-any.whl |
|---|---|
| Size | 23.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
781db1395fbc540ca867b772d8c8891ad2d68c95b3c572eb5ae933a1b7463244
|
|
BLAKE2b-256 checksum How to use checksums |
8fc1af895a5f94c166c92a52de3e6a4ae8fb30ac1ff3b6f68f88be6e57388011
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
