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

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

1. Download the latest release: get the Linux x64 archive from the releases page of https://gitlab.com/octomy/octomy.

2. Extract the archive:

tar -xzf <release>-linux-x64.tar.gz
cd <release>

3. Run the applications:

# Run the Agent
./agent

# Run the Remote
./remote

# Run the Hub
./hub

Building from source

The source is at https://gitlab.com/octomy/octomy. To build the applications yourself, read Build from source. Kiln is the project's build system: kiln check, then kiln build --install. Where to find kiln, and what to do when kiln check gives a fix line, is in Start here.

Android installation

From APK

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

Building for Android

To build the Android package yourself, read Build for Android. Kiln makes the package, for example kiln package apk src/hub, with the SDK and the NDK named in the checkout's .kiln.local. The kiln reference lists every android.* key.

Raspberry Pi installation

Recommended image

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

Installation steps

1. Update your system:

sudo apt update && sudo apt upgrade -y

2. Install Qt dependencies:

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

3. Install the applications as the Linux steps above say.

4. Auto-start on boot (optional):

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

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

[Install]
WantedBy=multi-user.target
EOF

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

Verify installation

After installation, verify everything is working:

Check version

./agent --version
# Output: the application name and its version, such as 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. Where that directory is depends on the platform: see Data location. 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:

<data directory>/
├── agent/
│   └── <personality>/           ← one Agent Node Personality (NID)
│       ├── keystore.json        (inside the active Sentient hive)
│       └── addressbook.json
├── remote/
│   └── <personality>/           ← one Remote Node Personality (NID)
│       ├── keystore.json
│       └── addressbook.json
└── 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