Quickstart Guide

System requirements

EmbodyX runs on an edge compute node located at your facility. The following hardware and software are required before you begin.

Hardware

Software

• Ubuntu 22.04 LTS (kernel 5.15+)
• NVIDIA Driver 525+ with CUDA 12.0+
• Docker 24.0+ with NVIDIA Container Toolkit
• Python 3.11+ (for SDK usage)

Install runtime

The EmbodyX runtime ships as a Docker image. Your account credentials from the dashboard are required to pull it.

1. Log in to the EmbodyX container registry

docker login registry.embx.io
# Enter your account email and API key when prompted

2. Pull the runtime image

docker pull registry.embx.io/runtime:latest

3. Create the runtime configuration directory

mkdir -p /opt/embx/config
mkdir -p /opt/embx/logs

4. Copy the starter configuration

docker run --rm registry.embx.io/runtime:latest \
  embx-init --output /opt/embx/config/embx.yaml

Open /opt/embx/config/embx.yaml in your editor. At minimum, set api_key and arm.adapter before proceeding.

FANUC adapter

The FANUC adapter connects to the R-30iB or R-30iB Plus controller over Ethernet using the FANUC Robot Interface (FRI) library. The controller must be on the same VLAN as the edge node.

Controller configuration

1. On the teach pendant, navigate to MENU > SYSTEM > Host Comm > TCP/IP.
2. Set a static IP for the controller (for example, 192.168.10.10).
3. Enable the FANUC FRI server: MENU > SYSTEM > Config > Remote Options > FRI Enable: TRUE.
4. Set the edge node's IP address in the allowed host list.

embx.yaml settings for FANUC

arm:
  adapter: fanuc_r30ib
  fanuc:
    controller_ip: "192.168.10.10"
    port: 18735
    program_slot: 1
    # Speed override during evaluation runs (0.1 = 10%, recommended first run)
    speed_override: 0.3

Verify connection

docker run --rm --network host \
  -v /opt/embx/config:/config \
  registry.embx.io/runtime:latest \
  embx-check-arm --config /config/embx.yaml
# Expected: ARM OK | FANUC R-30iB | Serial: XXXXXXX | FRI: connected

KUKA adapter

The KUKA adapter uses KUKA Robot Sensor Interface (RSI) for real-time communication with KR C4 or KR C5 controllers.

Controller configuration

1. Install the RSI software option on the KR C4/C5 controller.
2. Assign a static IP (for example, 192.168.10.20) via WorkVisual > Network Settings.
3. Upload the EmbodyX RSI XML descriptor using WorkVisual. The descriptor file is included in the runtime Docker image at /adapters/kuka/embx_rsi.xml.

embx.yaml settings for KUKA

arm:
  adapter: kuka_krc4
  kuka:
    controller_ip: "192.168.10.20"
    rsi_port: 49152
    cycle_time_ms: 4
    speed_override: 0.3

Universal Robots adapter

The UR adapter uses the URScript real-time interface (RTDE) available on UR3e, UR5e, UR10e, UR16e, and newer e-Series arms.

Arm configuration

1. On the teach pendant, go to Settings > System > Remote Control and enable remote operation.
2. Set a static IP via Settings > System > Network.
3. No additional software installation is required on the UR controller.

embx.yaml settings for UR

arm:
  adapter: ur_rtde
  ur:
    robot_ip: "192.168.10.30"
    rtde_port: 30004
    speed_override: 0.3
    # ur_model: ur5e, ur10e, ur16e (auto-detected if omitted)
    ur_model: "ur5e"

ABB OmniCore adapter

The ABB adapter uses RobotWare OmniCore's RWS (Robot Web Services) REST interface. Requires OmniCore C30 or C90 controller with RobotWare 7.0+.

embx.yaml settings for ABB

arm:
  adapter: abb_omnicore
  abb:
    controller_ip: "192.168.10.40"
    rws_port: 80
    username: "Default User"
    speed_override: 0.3

Configuration reference

The following settings in /opt/embx/config/embx.yaml apply to all arm adapters.

First task

With the arm connected and configuration validated, start the runtime and submit your first task.

Start the runtime

docker run -d --name embx-runtime \
  --runtime=nvidia \
  --network host \
  --device /dev/video0:/dev/video0 \
  -v /opt/embx/config:/config \
  -v /opt/embx/logs:/logs \
  registry.embx.io/runtime:latest

Verify the runtime is ready

docker logs embx-runtime | tail -20
# Wait for: [READY] EmbodyX runtime v2.x.x - arm connected, model loaded

Submit a task via Python SDK

from embx import EmbodyXClient

client = EmbodyXClient(
    api_key="your_api_key",
    runtime_host="localhost"
)

# Submit a simple pick-and-place task
task = client.tasks.submit(
    instruction="Pick the cylinder from the left bin and place it in the red tray."
)

# Stream status updates
for event in task.stream():
    print(event.status, event.message)

Expected output

SCENE_CAPTURE     Building scene embedding...
TASK_CONDITION    Encoding instruction...
ACTION_GENERATE   Generating trajectory at 25 Hz...
ARM_EXECUTING     Arm in motion...
SUCCESS           Task completed. Grasp confidence: 0.97

Edge deployment

For production deployments without an internet connection, EmbodyX supports fully air-gapped operation. The inference model and all dependencies are bundled in the Docker image. The only outbound connection the default configuration makes is to the cloud management plane for model updates and usage analytics. Both can be disabled:

cloud:
  model_updates: false   # Disable automatic model updates
  analytics: false       # Disable usage reporting
  management_plane: false # Full air-gap mode (Enterprise only)

In air-gap mode, model updates are delivered as container image updates via your internal container registry. Contact the integration team to set up the update channel for your facility's network policy.