Quickstart

Connect your robot to cloud-hosted Vision-Language-Action (VLA) models in minutes. Servo connects model inputs and outputs directly to your existing Python functions, camera streams, or motor drivers without requiring custom wrappers or configuration files.

Preview. The servo.connect API is currently in developer preview and not yet shipped in general availability. Early feedback and testing are welcome.

Prerequisites

Before starting, make sure you have:

Python 3.10+ installed
Network access to your Servo control-plane URL
A Servo account or API key

Step 1: Install and authenticate

Install the Servo client package:

pip install 'servo-client>=0.4,<0.5'
export SERVO_BASE_URL="https://<your-servo-control-plane>"

On a development machine with a browser, sign in interactively:

servo login

For headless robot computers (such as onboard IPCs accessed over SSH), generate an API key on your development machine with servo key create --label robot-cell-01, then export it on the robot:

export SERVO_API_KEY="sk_servo_..."

Step 2: Test on your laptop (no hardware needed)

You do not need physical hardware on hand to start developing. Use mock=True to exercise Servo’s local bindings and bounded control loop on your development computer. Mock sessions do not contact a hosted model or require credentials:

from servo.universal import connect

# Create a local deterministic mock session
session = connect(
    "allenai/MolmoAct2-BimanualYAM",
    mock=True,
)

# Run a test episode
report = session.run(task="pick up the red cup", max_steps=5)
print(report)

[Servo RunReport: COMPLETED]
Duration: 0.17s | Steps: 5 (29.9 Hz) | Status: completed

This generates synthetic camera frames and joint telemetry for the built-in MolmoAct2 development profile, validates the local observation bindings and action loop, and returns a structured RunReport. Exact elapsed time and measured frequency vary slightly by host. Use a non-mock session to validate credentials, network transport, and a hosted model.

Step 3: Connect your real robot (`rig.py`)

When you are ready to connect physical hardware, create rig.py to bind your real cameras and motor methods using observe and act:

from servo.universal import camera, connect
from my_robot import BimanualYam

# 1. Initialize your robot driver or controller
arm = BimanualYam()

# 2. Connect model inputs and outputs to your hardware
session = connect(
    "allenai/MolmoAct2-BimanualYAM",
    region="us-west-2",
    observe={
        "top": camera(serial="250423122040"),
        "left": camera(serial="402323071792"),
        "right": camera(serial="402323071794"),
        "state": arm.get_joint_positions,
    },
    act=arm.apply_joint_targets,
)

# 3. Run a live episode
report = session.run(task="pick up the red cup", timeout_s=20.0)
print(report)

Servo automatically starts its local background daemon (servo daemon) on first use if it isn’t already running. For production robot cells, run servo daemon --install-service once to install it as a supervised system service.

Understanding `observe` and `act`

Channel	Role	What to provide	Notes
`observe`	Sensory Inputs	Dictionary of camera handles (`camera()`, from `servo.universal`) and state callables	Keys match the model’s required sensor slots (e.g. `top`, `left`, `right`, `state`).
`act`	Motor Outputs	Function accepting continuous target joint arrays (e.g. `(14,) float32`)	Called at 30 Hz. Return `None` on success, `{"done": True}` to complete early, or raise to trigger safety hold.

Step 4: Zero-motion preflight (`servo check-rig`)

Before powering on physical motors, run zero-motion preflight verification against your script:

servo check-rig rig.py

servo check-rig imports rig.py and validates all camera connections, network latency, and motor bindings up to the point of motion without commanding any motor movement:

[Servo Diagnostic Preflight: Bimanual YAM]
✔ Local Sidecar: Active (/run/servo/agent.sock)
✔ Network Transport: Connected to us-west-2 (RTT: 17.8 ms)
✔ Sensor Sources:
    - 'top':   Stream 0 (640x360 RGB) -> Hardware encoder ready
    - 'left':  Stream 1 (640x360 RGB) -> Hardware encoder ready
    - 'right': Stream 2 (640x360 RGB) -> Hardware encoder ready
    - 'state': 14-D vector verified
✔ Actuator Sink: Registered & Responsive
✔ Remote Cockpit: Ready at https://servo.run/cockpit/bimanual-yam-01
STATUS: READY FOR LIVE EXECUTION.

To validate scripts before hardware arrives, run servo check-rig rig.py --mock.

Step 5: Camera selection

Automatic camera discovery is not exposed by the customer CLI yet. For a generic V4L2 camera, use camera(0) with a verified device index. Supported Intel RealSense installations can use a known vendor serial with camera(serial="..."). Do not infer camera roles from USB enumeration order. Verify each stream and bind its role explicitly; stable serials prevent streams from swapping when device indices change after a reboot.

Step 6: Live monitoring and interventions

While an episode runs, you can monitor and control execution interactively:

Remote Web Cockpit: Open the URL displayed by servo check-rig to view real-time camera streams and latency charts in your browser.
Teleoperation Interventions: Take manual control using a gamepad or keyboard from the cockpit at any time. Servo smoothly blends velocity trajectories to eliminate motion jolts.

Programmatic Pause & Resume:

# Pause autonomous actions (holds current position safely):
session.pause()

# Resume policy execution:
session.resume()

Direct control loops (`servo.Policy`)

If you prefer managing your own while loop (for custom safety filters, step-by-step logging, or custom simulation wrappers), use servo.Policy:

import servo
from my_robot.env import RobotEnv

env = RobotEnv()
policy = servo.Policy("allenai/MolmoAct2-BimanualYAM", robot="bimanual-yam-01")

for step in range(300):
    obs = env.get_obs()

    action = policy(
        top=obs["front_camera"],
        left=obs["left_camera"],
        right=obs["right_camera"],
        state=obs["joint_positions"],
        task="pick up the red cup",
    )

    env.step(action)

policy(...) returns the first row of the chunk the model returned, directly usable by env.step(action). It does not buffer or prefetch — every call is one real network round trip — so call it no faster than your model’s round-trip allows, or add your own buffering for a tighter loop.

Next steps

Read the in-depth Robot Integration Guide to learn about ROS 2 topics, custom sensor contracts, and fault handling.
Scale up to multi-robot deployments in Robot Fleets.
Review all methods and configuration options in the Python API Reference.

Get started

Use Servo

Prerequisites

Step 1: Install and authenticate

Step 2: Test on your laptop (no hardware needed)

Step 3: Connect your real robot (`rig.py`)

Understanding `observe` and `act`

Step 4: Zero-motion preflight (`servo check-rig`)

Step 5: Camera selection

Step 6: Live monitoring and interventions

Direct control loops (`servo.Policy`)

Next steps

​Prerequisites

​Step 1: Install and authenticate

​Step 2: Test on your laptop (no hardware needed)

​Step 3: Connect your real robot (rig.py)

​Understanding observe and act

​Step 4: Zero-motion preflight (servo check-rig)

​Step 5: Camera selection

​Step 6: Live monitoring and interventions

​Direct control loops (servo.Policy)

​Next steps

Prerequisites

Step 1: Install and authenticate

Step 2: Test on your laptop (no hardware needed)

Step 3: Connect your real robot (`rig.py`)

Understanding `observe` and `act`

Step 4: Zero-motion preflight (`servo check-rig`)

Step 5: Camera selection

Step 6: Live monitoring and interventions

Direct control loops (`servo.Policy`)

Next steps