Quickstart

Send NumPy inputs; get action arrays. Your application reads sensors and applies actions. Requires Python 3.12+ on macOS/Linux, a Servo account, and a connected Hugging Face account. No local GPU or robot registration is needed. Save Python examples using their shown filenames; run them with python FILENAME.py.

Install and sign in

Install Servo and sign in:

your computer

python -m venv .venv
source .venv/bin/activate
python -m pip install servo-client
servo login
servo whoami

On a headless computer, follow the printed sign-in link and code. CLI and Python share your saved sign-in; telemetry is configured automatically.

Inspect the model inputs

Read the checkpoint contract before allocating capacity or creating arrays:

CLI
Python

Inspect the checkpoint:

your computer

servo model inspect hf://npow/pi05-yam-red-cap-full-7500 \
  --revision 39c6876521b3d8363452bed6731c8705b3944c24

Sample output:

Sample output

Checkpoint: npow/pi05-yam-red-cap-full-7500@39c6876521b3d8363452bed6731c8705b3944c24
Runtime: openpi
Input contract: resolved
Input middle (image): [224, 224, 3], HWC, uint8
Input left (image): [224, 224, 3], HWC, uint8
Input right (image): [224, 224, 3], HWC, uint8
Input state (state): [7], float32
Action chunk shape: [15, 7]
Served from its own files: yes

Inspect the checkpoint with Python:

inspect_checkpoint.py

import servo

sv = servo.Servo()
inspection = sv.models.inspect_checkpoint(
    "https://huggingface.co/npow/pi05-yam-red-cap-full-7500",
    revision="39c6876521b3d8363452bed6731c8705b3944c24",
)
contract = inspection.input_contract
print(contract.resolution)
for feature in contract.inputs or []:
    print(feature.name, feature.shape, feature.dtype, feature.layout)
print("Actions:", contract.outputs["actions"].shape)

Sample output:

Sample output

resolved
middle (224, 224, 3) uint8 HWC
left (224, 224, 3) uint8 HWC
right (224, 224, 3) uint8 HWC
state (7,) float32 None
Actions: (15, 7)

Use the exact input keys, shapes and dtypes shown above. HWC means height, width, channels; None means no image layout. Continue only when the contract is resolved. The checkpoint documentation defines camera placement, state units and action meanings.

Import and deploy

CLI
Python

Import, then deploy using the returned model ID:

your computer

servo model import hf://npow/pi05-yam-red-cap-full-7500 \
  --revision 39c6876521b3d8363452bed6731c8705b3944c24

Run the returned MODEL_ID= assignment in your shell, then deploy:

your computer

servo model deploy "$MODEL_ID" --city "Zurich, Switzerland" --wait --timeout 900

Save the printed deployment ID; this command waits for readiness.

Import the checkpoint and wait for deployment readiness:

deploy_checkpoint.py

import servo

sv = servo.Servo()
model = sv.models.import_checkpoint(
    "https://huggingface.co/npow/pi05-yam-red-cap-full-7500",
    revision="39c6876521b3d8363452bed6731c8705b3944c24",
)
deployment = model.deploy(city="Zurich, Switzerland")
print("DEPLOYMENT_ID=" + deployment.id)
deployment.wait(timeout_s=900)

Deployment allocates hosted capacity and requires an organization member or API key. The first import may download weights and compile; both examples wait for readiness. Servo aims to provision for the fastest end-to-end latency. Repeated requests for the same model and site reuse the deployment. A timeout does not cancel it: inspect or stop it below.

Provide model inputs and predict

Create sample arrays matching the inspected contract and make one prediction:

first_prediction.py

import numpy as np
from numpy.random import randint
import servo

sv = servo.Servo()
deployment = sv.deployments.get(input("Deployment ID: "))
policy = deployment.policy()

inputs = {
    "middle": randint(0, 256, (224, 224, 3), dtype=np.uint8),
    "left": randint(0, 256, (224, 224, 3), dtype=np.uint8),
    "right": randint(0, 256, (224, 224, 3), dtype=np.uint8),
    "state": np.zeros(7, dtype=np.float32),
}
with sv.session(policy, instruction="pick up the red cap and place it in the black box") as session:
    chunk = session.predict(inputs=inputs)
print(chunk.actions)

Save the code above, or download and run it:

your computer

curl -fsSL https://api.orchestrallabs.ai/docs/downloads/first_prediction.py -o first_prediction.py
python first_prediction.py

Enter your saved deployment ID when prompted.Expect 15 × 7 action values. Random images and a zero state check connectivity; they are not useful robot observations. The model rejects a state outside the range its checkpoint declares, so use a real reading, not random state values. Servo handles model preprocessing. Servo does not apply them to hardware; your application owns sensor capture, action interpretation and hardware limits.

Inspect or stop the deployment

CLI
Python

Inspect the deployment, then stop it:

your computer

servo deployment show "$DEPLOYMENT_ID"
servo deployment logs "$DEPLOYMENT_ID"
servo deployment stop "$DEPLOYMENT_ID"
servo deployment show "$DEPLOYMENT_ID"

Inspect the deployment, then stop it:

stop_deployment.py

import servo

sv = servo.Servo()
deployment = sv.deployments.get(input("Deployment ID: "))
print(deployment.status)
deployment.delete()
deployment.wait_retired(timeout_s=300)
print(deployment.status)

Run the returned DEPLOYMENT_ID= assignment in your shell first. CLI logs prints authenticated dashboard links. delete() and stop request teardown; confirm retired through wait_retired() or repeated show. Closing Python or a session leaves the deployment running and capacity allocated.

For real sensors and action execution, continue to your control loop.

Get started

Guides

Reference