Your first Agent

In this tutorial, you'll set up your first OctoMY™ Agent - the node that runs on your robot.

What you'll learn

• Starting an Agent for the first time
• Understanding the "birth" process
• Configuring hardware (optional)
• Navigating the Agent interface

Prerequisites

• OctoMY™ installed (see Installation)
• A device to run the Agent (computer, Raspberry Pi, or Android phone)

Step 1: Start the Agent

Open a terminal and run:

./agent --personality MyFirstRobot

The --personality flag gives your Agent a name. This creates a separate Node Identity (NID) with its own data, sitting underneath your Sentient Identity (SID) — the human-operator identity that owns this and any other Nodes you create.

Pro Tip

Use descriptive personality names like "KitchenBot" or "GardenRover". You can run many Agents on the same machine, each with its own NID — and all of them owned by your single Sentient. You can switch between them without restarting the app.

Step 2: The birth process

When you start an Agent for the first time, it goes through a "birth" process:

What happens during birth

1. Key Generation: A unique RSA key pair is created. This is your Agent's Node Identity (NID) — distinct from your Sentient Identity (SID), which represents you. Your SID owns this NID, and can own others.

2. Personality Creation: From the NID key, OctoMY™ derives:

   • A unique identicon (visual avatar)
   • A generated name (like "Thundering Walrus")
   • Theme colors
   • Voice characteristics

3. Service Initialization: Core services start up in sequence.

Did You Know?

The identicon is mathematically derived from the NID's public key. The same key always produces the same identicon — useful for visually verifying identity across devices. Your Sentient has its own identicon too (a face); this one is the Agent's.

Step 3: Explore the interface

After birth, you'll see the main Agent window:

The face

The large face display shows your robot's "expression." This is purely decorative but makes your robot feel more alive.

The menu

Tap the menu icon (☰) to access:

Step 4: Configure hardware (optional)

If your Agent has attached hardware (motors, sensors), configure it now.

Access hardware settings

1. Tap ☰ Menu → Hardware
2. Select your controller type

Supported controllers

Example: ArduMY setup

1. Connect your Arduino via USB
2. In Hardware settings, select ArduMY
3. Choose the serial port (e.g., /dev/ttyUSB0)
4. Configure your actuators:

Pro Tip

Don't have hardware yet? Select "Virtual" controller to continue learning. You can add real hardware later without losing your Agent's identity.

Step 5: Enable discovery

For the Remote to find your Agent, enable discovery:

1. Tap ☰ Menu → Settings
2. Enable Auto Discovery

The Agent will now broadcast its presence on the local network.

Step 6: Verify your Agent

Check that your Agent is ready:

Check status

Look at the status bar at the bottom of the window:

View your identity

Go to ☰ Menu → Utilities → Identity to see:

Troubleshooting

Agent won't start

"Could not bind to port 8124"

Another process is using the port. Either stop the other process or use a different port:

./agent --personality MyRobot --port 8125

Hardware not detected

"No serial ports found"

1. Check the physical connection
2. Verify you have permission: ls -la /dev/ttyUSB*
3. Add yourself to the dialout group: sudo usermod -a -G dialout $USER

Discovery not working

"No Remotes can find me"

1. Ensure both devices are on the same network
2. Check firewall allows UDP on port 8124
3. Try manual pairing using QR code instead

What you've accomplished

You now have a running Agent with:

• A unique Node Identity (NID), owned by your Sentient
• A generated personality (identicon, name, colors, voice)
• (Optionally) configured hardware
• Discovery enabled for Remotes to find

This is one Agent out of potentially many your Sentient can own. When you want to add another (a workshop bot, a garden bot, a sandbox for testing), repeat this tutorial with a different --personality name and you'll have a second Node under the same Sentient. The Identity Switching page covers how to move between them.

Next steps

Your first Remote - Set up a controller for your Agent