Python API

Install with pip install servo-client; authenticate with servo login. For runnable CLI/Python examples, use the quickstart. These signatures show common options.

Client and models

servo.Servo(base_url=None, api_key=None, timeout=3600.0) -> Servo
sv.models.inspect_checkpoint(source, *, revision="main", secret=None) -> ModelInspection
sv.models.import_checkpoint(source, *, revision="main", name=None, wait=True, timeout_s=2400) -> Model
sv.models.get(slug) -> Model
sv.models.list() -> list[Model]
model.wait(*, timeout_s=2400) -> Model
model.deploy(robot=None, *, city=None, region=None, latitude=None, longitude=None, deployment_key=None, idle_minutes=None, max_sessions=None) -> Deployment

source accepts a Hugging Face URL, hf://ORG/REPO, or ORG/REPO. Pin revision to a commit for reproducibility. Inspection exposes input_contract: resolution, input names/shapes/dtypes and output shape. Import waits for preparation unless wait=False. Choose one placement: city, region, coordinates, or a robot’s saved site. The same model and site reuse a deployment; deployment_key distinguishes separate deployments. Capacity stays warm until stopped unless idle_minutes is set.

Deployments

sv.deployments.get(deployment_id) -> Deployment
deployment.wait(*, timeout_s=2400) -> Deployment
deployment.policy(robot=None) -> Policy
deployment.delete() -> Deployment
deployment.wait_retired(*, timeout_s=300) -> Deployment

Read id and status; wait confirms readiness. A timeout leaves allocation running. delete requests shutdown; wait_retired confirms it.

Predictions

sv.session(policy, *, instruction=None) -> Session
session.predict(*, inputs, instruction=None) -> ActionPrediction
session.act(observation, instruction=None) -> ActionPrediction
session.close() -> None
sv.sessions.list(*, robot=None) -> list[SessionRecord]
sv.sessions.get(session_id) -> SessionRecord

Use sessions as context managers; listed session records are read-only. predict accepts checkpoint-named arrays; act accepts structured observations. A per-call instruction overrides the session default for that request.

Value	Meaning
`inputs`	`Mapping[str, Any]`: inspected feature names to matching NumPy arrays
`chunk.actions`	Action rows, shaped `[horizon, action_dim]`
`chunk.horizon`, `chunk.action_dim`	Rows and channels per row
`chunk.telemetry`, `chunk.raw`	Returned timing and response details

Extra input keys, including metadata, are rejected for checkpoint-named inputs. Servo handles preprocessing. Your robot application owns action execution and sensor capture. Closing a session leaves the deployment running.

Robots and access

sv.robots.get(name_or_id) -> Robot
sv.robots.list() -> list[Robot]
sv.access.grant(subject, *, robot, role) -> None
sv.access.revoke(subject, *, robot) -> None
sv.access.list(*, robot) -> list[Grant]

Robot identity is optional for checkpoint inference. subject is a member email or Google Group; role is read, write or admin. See identity and access.

Local recovery

For a custom controller, see local recovery.

session.open() -> Session
session.configure_recovery(*, handler, controller, takeover_timeout_s=1.0) -> RecoveryRegistration
registration.notify_starvation(*, queue=None) -> None
registration.stop() -> Awaitable[None]
recovery.resume(*, timeout_s=10.0) -> Awaitable[ResumeResult]
recovery.hold(reason) -> str
recovery.release_hold(token) -> None
recovery.record_action(name, *, outcome, details) -> None

Errors expose code, message and detail; see errors.

Get started

Guides

Reference

Client and models

Deployments

Predictions

Robots and access

​Client and models

​Deployments

​Predictions

​Robots and access

Client and models

Deployments

Predictions

Robots and access