> ## Documentation Index
> Fetch the complete documentation index at: https://servo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Servo and connect your robot in 5 minutes.

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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```python theme={null}
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)
```

```text theme={null}
[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`:

```python theme={null}
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:

```bash theme={null}
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:

```text theme={null}
[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:

1. **Remote Web Cockpit**: Open the URL displayed by `servo check-rig` to view real-time camera streams and latency charts in your browser.
2. **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.
3. **Programmatic Pause & Resume**:
   ```python theme={null}
   # 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`:

```python theme={null}
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](/guides/robots) to learn about ROS 2 topics, custom sensor contracts, and fault handling.
* Scale up to multi-robot deployments in [Robot Fleets](/guides/fleet-deployment).
* Review all methods and configuration options in the [Python API Reference](/reference/python-api).