About this proposal

What these pages propose, where they deviate from the design specs, and what ships today.

These pages describe the proposed Servo experience for a robotics researcher. They are a design review, not a reference for the released SDK: the names, signatures, and commands here need the matching implementation before the examples run. The site banner is the only place that says so, on purpose, so every page reads as it will once shipped.

What to read

Start with the Quickstart, then First motion. Read the other pages when their question is yours.

Your task	Page
Use chunks in your own controller	Keep your own loop
Reach a private bucket or read the contract	Choose a model
Give a lab-mate the robot, or take it back	Identity and auth
Look up a signature or a command	Python API, CLI

Decisions these pages make concrete

• Three roles on a robot: read, write, admin. The line a lab cares about is whether a person may make the arm move, write covers starting sessions and running episodes, and deploying a model needs only membership. Setup moves nothing and runs on the robot computer as the robot, so it needs no role.
• Models are paths, and there is one deployment per model revision and region; deploy is safe to call again, and a session binds a deployment to one robot and one instruction.
• predict and send_action are the two verbs of the loop.
• check never moves the arm; run applies the guard, returns to the rest pose on every ending, and records every episode.
• run bounds an episode by seconds, by chunks, or both, so a step count for comparing episodes doesn’t have to drift with round-trip latency.
• Two safety layers, not one: max_jump is a boundary-only guard on the first row of a new chunk; max_relative_target is a continuous per-step clamp applied to every row sent.
• run paces sends at the model’s own cadence (1/dt_s) by default and adapts down when latency can’t sustain it, rather than sending as fast as the loop can go; report.recommended_fps is what it settled on.
• A chunk switch blends over a short window instead of cutting over on the row.
• Instruction is bound to the session, not passed per predict call, so a new instruction is a new session.
• Serving runs in Servo’s cloud near the robot. Serving on a lab’s own GPU is documented for engineers in the repository at docs/guides/serve-a-model-on-your-own-gpu.md and is not part of this proposal.

Deviations from specs 045 and 046

Spec says	These pages say
Robot roles viewer, operator, developer, admin (045 FR-060)	read, write, admin; operator and developer both become write
Fleets are a second capacity noun (sv.fleets)	Folded into one deployment per model revision and region, with a session per robot
Robot apps, releases, channels, canary and phased rollouts, labels, pins, and servo deploy for code (046)	Out of the customer pages; the robot computer runs a script you start yourself
servo join --service installs the agent	The agent is installed by default
A session keeps model history and is reset explicitly	A session binds a deployment to one robot and one instruction and keeps one connection; predict keeps no history
robot.start dispatches a run to a listening app	Out of the customer pages; sessions run on the robot computer
Recording is opt-in	Every run records unless record=False

Proposed names and what ships today

Proposed	Today
servo.Servo() from the saved login, or the agent on the robot computer	SERVO_BASE_URL and an API key in the environment on every machine
sv.models.get(path), sv.models.list()	sv.models.get(slug), sv.models.list(robot)
sv.robots.add, servo robot add, servo join, servo robot setup	Registration is SDK-only through sv.robots.setup(...); servo robot list exists; servo check-rig checks a rig script without motion; attach takes runtime=, a manifest, or a configuration; no YAM driver ships
session.predict(robot), robot.send_action(row)	robot.observe(), robot.execute(prediction), policy.act()
ActionChunk with horizon, action_dim, and dt_s	ActionPrediction
session.check(robot, seconds=) with guard; session.run(robot, record=True, max_jump=, max_relative_target=) bounded by seconds and/or chunks	check(policy) runs two shadow chunks; recording exists only on the direct serving path; no rest pose on the hosted loop; no chunk-count bound, only a caller-managed loop; no continuous clamp exposed to the caller
model.deploy(), deployment.start, deployment.stop, idle_minutes, --region	model.deploy(robot) for one robot and sv.fleets.deploy(robots=[…]) for several; deployment.policy(robot); deployment.delete(); no idle stop; region is set by sv.robots.setup(region=), and deploy takes none
servo session …, servo episode …, sv.sessions	sv.session(policy) over an in-process client only; no session or episode commands
servo access …, sv.access, read, write, admin	No access commands; roles exist only in the specs
servo model …, servo deployment show, servo deployment wait	servo deployment list and servo deployment stop only

Useful feedback

While reading, note the first place you had to guess, look up source code, or read a page you did not need. Name any step you would remove. Examples use one lab’s robot and checkpoint; nothing on this site is a measured result, and rendering checks do not establish model quality or physical behavior.