Installation

This tutorial walks you through installing OctoMY™ on your computer or device.

What you'll need

For development: A computer running Linux, Windows, or macOS
For running an Agent: An Android device or Raspberry Pi
For running a Remote: A phone, tablet, or desktop computer

Choose your platform

Platform	Recommended For	Status
Linux (Desktop)	Development, Hub	Full support
Android	Agent, Remote	Full support
Raspberry Pi	Agent	Full support
Windows	Development	Partial support
macOS	Development	Partial support

Pro Tip

For the fastest setup, use Linux with pre-built binaries. You can be up and running in under 5 minutes.

Linux installation

From pre-built binaries

Download the latest release:

# Download from GitHub releases
wget https://github.com/mrdeveloperdude/OctoMY/releases/latest/download/octomy-linux-x64.tar.gz

Extract the archive:

tar -xzf octomy-linux-x64.tar.gz
cd octomy

Run the applications:

# Run the Agent
./agent

# Run the Remote
./remote

# Run the Hub
./hub

Building from source

Building from source is recommended for development or to get the latest features.

Prerequisites

Install the required dependencies:

# Ubuntu/Debian
sudo apt update
sudo apt install -y \
    build-essential \
    git \
    qt6-base-dev \
    qt6-multimedia-dev \
    qt6-positioning-dev \
    qt6-serialport-dev \
    qt6-bluetooth-dev \
    qt6-svg-dev \
    qt6-sensors-dev \
    qt6-tools-dev \
    libmbedtls-dev

# Fedora
sudo dnf install -y \
    gcc-c++ \
    git \
    qt6-qtbase-devel \
    qt6-qtmultimedia-devel \
    qt6-qtpositioning-devel \
    qt6-qtserialport-devel \
    qt6-qtconnectivity-devel \
    qt6-qtsvg-devel \
    qt6-qtsensors-devel \
    mbedtls-devel

Clone and build

# Clone the repository
git clone https://github.com/mrdeveloperdude/OctoMY.git
cd OctoMY

# Build using Qbs
qbs build -f project.qbs

# The executables are in default/install-root/usr/local/bin/
./default/install-root/usr/local/bin/agent

Android installation

From APK

Download the APK from the releases page
Enable "Install from Unknown Sources" in your Android settings
Install the APK by opening the downloaded file
Launch OctoMY™ from your app drawer

Building for Android

For Android development, you'll need:

Android SDK
Android NDK
Qt for Android

# Configure Qt for Android in your environment
export ANDROID_SDK_ROOT=/path/to/android-sdk
export ANDROID_NDK_ROOT=/path/to/android-ndk

# Build for Android
qbs build -f project.qbs profile:android

Raspberry Pi installation

Recommended image

Use Raspberry Pi OS (64-bit) for best compatibility.

Installation steps

Update your system:

sudo apt update && sudo apt upgrade -y

Install Qt dependencies:

sudo apt install -y \
    qt6-base-dev \
    qt6-serialport-dev \
    qt6-bluetooth-dev \
    libmbedtls-dev

Download or build OctoMY™ following the Linux instructions above.
Auto-start on boot (optional):

# Create a systemd service
sudo tee /etc/systemd/system/octomy-agent.service << 'EOF'
[Unit]
Description=OctoMY Agent
After=network.target

[Service]
Type=simple
User=pi
ExecStart=/home/pi/octomy/agent --personality MyRobot
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable octomy-agent
sudo systemctl start octomy-agent

Verify installation

After installation, verify everything is working:

Check version

./agent --version
# Output: OctoMY Agent 1.0.0

Run a quick test

# Start the Agent
./agent --personality TestAgent

# In another terminal, start the Remote
./remote --personality TestRemote

You should see both applications start and display their main windows.

Directory structure

After first run, OctoMY™ creates its data directory. The layout below shows the per-personality view — what you see from outside the encryption. The actual contents live inside an encrypted hive owned by your Sentient:

~/.local/share/OctoMY™/
├── OctoMY Agent/
│   └── <personality>/           ← one Agent Node Personality (NID)
│       ├── keystore.json        (inside the active Sentient hive)
│       └── addressbook.json
├── OctoMY Remote/
│   └── <personality>/           ← one Remote Node Personality (NID)
│       ├── keystore.json
│       └── addressbook.json
└── OctoMY Hub/
    └── <personality>/           ← one Hub Node Personality (NID)
        ├── keystore.json
        └── addressbook.json

Each <personality>/ folder is one Node Identity. All Nodes you create live inside a single Sentient hive on disk (named SID-<your-id>); the per-personality data is part of that hive's contents.

Did You Know?

Each personality gets its own isolated data — different keystore.json, different contacts, different trust relationships. The Sentient hive that owns them adds another layer of isolation: a second Sentient on the same machine would have a completely separate set of Nodes. See Sentient Identity for how the two layers relate, and Identity Switching for how to move between them.

Troubleshooting

"Qt platform plugin could not be loaded"

Install the missing Qt platform plugins:

# Ubuntu/Debian
sudo apt install qt6-base-plugins

# Or set the platform explicitly
export QT_QPA_PLATFORM=xcb
./agent

"Permission denied on /dev/ttyUSB0"

Add your user to the dialout group for serial port access:

sudo usermod -a -G dialout $USER
# Log out and back in for the change to take effect

"Cannot connect to X server"

For headless operation, use the offscreen platform:

export QT_QPA_PLATFORM=offscreen
./agent

Pro Tip

If you're running on a Raspberry Pi without a display, the offscreen platform is the way to go. You can still access OctoMY™ remotely via the Remote app.

Next steps

Now that OctoMY™ is installed, continue to:

Your first Agent - Set up your first robot node