Reference · Robots
- The language
- Agents and tools
- Model providers
- The Anthropic API
- Talking agents
- Standard library
- Glossary
- Package docs
- Telemetry
- Robots
- Servers
- Deploying
- tin.ad
- The tin command
- How it works
On this page
Robots
robot declarations, Pose and Angle, the built-in kinematic world and MuJoCo, the control loop and policy forms, the safety gate, arm.drive for agents, and run tapes.
Robots and policies are part of the language. The design follows the open-source strands-labs/robots (a Robot is a description plus a body, observe → policy → act, holds are not misses, one approval per run) in Tin's terms: joints checked at compile time, angles as units, the gate and the loop written in Tin so they run the same on every host.
Declaring a robot
robot Name = <registry id> declares a robot kind; Name() opens one and gives a
Robot<Name>. The one field is world:
robot Arm = so101 // the built-in kinematic world
robot Sim = so101 { world: mujoco } // MuJoCo physics (tin run)
fn main() {
var arm = Arm()
print(arm.jointNames().len)
} 6 An unknown id is an error listing the registry with the nearest name as the fix. robot is a
contextual word: elsewhere it is an ordinary name.
The registry
Generated by scripts/robots.mjs from MuJoCo Menagerie MJCF files (actuated joints in actuator
order, ranges, speed limits), with each file's URL, SHA-256 and license recorded.
| id | aliases | joints |
|---|---|---|
so101 | robotstudio_so101, so101_follower, so_arm101 | shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper |
so100 | trs_so_arm100, so100_follower, so_arm100 | Rotation, Pitch, Elbow, Wrist_Pitch, Wrist_Roll, Jaw |
panda | franka_panda, franka_emika_panda | joint1, joint2, joint3, joint4, joint5, joint6, joint7 |
ur5e | universal_robots_ur5e | shoulder_pan_joint, shoulder_lift_joint, elbow_joint, wrist_1_joint, wrist_2_joint, wrist_3_joint |
unitree_go2 | go2 | FL_hip_joint, FL_thigh_joint, FL_calf_joint, FR_hip_joint, FR_thigh_joint, FR_calf_joint, RL_hip_joint, RL_thigh_joint, RL_calf_joint, RR_hip_joint, RR_thigh_joint, RR_calf_joint |
unitree_g1 | g1 | left_hip_pitch_joint, left_hip_roll_joint, left_hip_yaw_joint, left_knee_joint, left_ankle_pitch_joint, left_ankle_roll_joint, right_hip_pitch_joint, right_hip_roll_joint, right_hip_yaw_joint, right_knee_joint, right_ankle_pitch_joint, right_ankle_roll_joint, waist_yaw_joint, waist_roll_joint, waist_pitch_joint, left_shoulder_pitch_joint, left_shoulder_roll_joint, left_shoulder_yaw_joint, left_elbow_joint, left_wrist_roll_joint, left_wrist_pitch_joint, left_wrist_yaw_joint, right_shoulder_pitch_joint, right_shoulder_roll_joint, right_shoulder_yaw_joint, right_elbow_joint, right_wrist_roll_joint, right_wrist_pitch_joint, right_wrist_yaw_joint |
stretch3 | hello_robot_stretch_3, stretch_3 | joint_left_wheel, joint_right_wheel, joint_lift, joint_wrist_yaw, joint_wrist_pitch, joint_wrist_roll, joint_gripper_slide, joint_head_pan, joint_head_tilt |
Pose, Angle and Observation
Angle is a unit type stored as radians: 0.5rad, 30deg,
a.rad(), a.deg(), a.sin(). Pose { joint: angle, ... }
sets joint targets; joints it leaves out hold. In the arguments of a method on Robot<R> the
names are checked against R, elsewhere against every declared robot. p.get(j),
p.with(j, a), p.joints(). arm.observe() gives an
Observation { t: Duration, joints: Joint[] } with o.at(j) (panics on an unknown
name) and o.get(j); a Joint has name, position and
velocity (rad/s). t is the robot's own clock.
Moving a robot
arm.act(pose) | write the targets, let one 20 ms period pass |
arm.reach(pose, 1s) | straight-line ramp, one gated step per period |
arm.wait(d) | hold every target while time passes |
arm.target() | the current targets as a Pose |
arm.safe(j, lo, hi) · arm.validate(f) | narrow a joint; add a check (see the gate) |
arm.estop() · arm.resume() · arm.stopped() | emergency stop: hold where the joints are, refuse every write |
A robot that moves is a var; methods take it inout.
Worlds
A world owns time and the bodies in it; the language owns everything else. The gate, the control loop, policies and tapes are Tin and run the same in every world. Pick one with the robot's one field:
robot Arm = so101 // kin
robot Sim = so101 { world: mujoco } // physics
robot Ref = so101 { world: py } // strands_robots
fn main() { } | World | Runs on | What moves the joints |
|---|---|---|
kin | every host | Tin: each joint a first-order servo (40 ms) within its speed and range, 2 ms steps. Not physics: no gravity, contacts or dynamics. |
mujoco | tin run, the playground, native | MuJoCo 4.0.1, Google DeepMind's WebAssembly build (@mujoco/mujoco, optional): gravity, contacts, the robot's own actuators. |
py | tin run | The reference library, strands_robots, through one Python process: its own models and gains. |
tin build --native links MuJoCo 4.0.1 statically (sh scripts/install-native.sh mujoco builds it
once) and writes the robot's verified files to ~/.tin/robots/<id>/: the executable needs only the
system libraries and prints the same digits as tin run. --target wasi refuses a mujoco
robot, and both refuse py, at build time with the reason.
MuJoCo. The robot opens in its Menagerie scene (floor and light), at the same start as
kin; the G1 humanoid starts from its stand keyframe. The scene and meshes are not shipped:
they are fetched on first use from MuJoCo Menagerie at one commit and every byte is checked against its
SHA-256 (src/robot-assets.ts), then kept in ~/.tin/cache/robots (the browser: its cache).
Targets go to the robot's own actuators by joint name: a position servo gets the target, a torque motor (Go2) a
PD loop each physics step, a velocity actuator (Stretch 3's wheels) a speed toward the target angle. One tick
is round(1/hz ÷ timestep) physics steps, so the clock never drifts and a run repeats bit for bit.
Robots: so101, unitree_go2, unitree_g1, stretch3.
In the playground a mujoco program shows its world on a canvas while it runs, one
frame per 1/15 s of simulated time, drawn by Tin's software renderer (no textures or shadows). The 11 MB
engine loads only for such a program: run the wave.
Parity. On the same model (strands_robots' SO-101) and the same targets, Tin's MuJoCo
world and strands_robots agree to 2.1×10⁻⁹ rad over a 2 s wave at 50 Hz (tests/robot-compare.test.ts,
tolerance 10⁻⁶). With Menagerie's SO-101, the default here, numbers differ from strands_robots' by a few
percent: different model files. kin numbers are not physics numbers.
Python. world: py finds Python like import py ($PYTHON, a
.venv next to the program, else python3) and refuses to open, with the install line,
when strands_robots is not importable there.
The control loop
arm.run(p, seconds, hz) and arm.runUntil(p, seconds, hz, stop) run round(seconds
× hz) ticks: observe → stop? → policy → gate → one period. They return
RunResult { steps, holds, misses, seconds, hz, stoppedBy, final, tape };
stoppedBy is steps, stopWhen, estop or
fault: why. A policy that returns None holds (counted, never a miss). A fault ends the run with every
joint holding where it is.
Policy forms
policy(f) | (Observation) => Option<Pose>; a function or lambda passed straight to run is wrapped for you: arm.run(wave, 5s, 50Hz) |
sequence([step(pose, 1s), ...]) | ramp waypoint to waypoint from the run's start targets, then hold the last |
chunked(f, n) | f returns Pose[]; one per tick, asked again every n ticks or when empty |
hold() | never writes |
perturb(p, seed, amount) | noise of up to ±amount, fixed by the seed |
replay(tape) | a recorded run's actions |
onnx(spec), hub(spec), remote(url) | a learned policy: below |
Learned policies: onnx, hub, remote
robot Body = g1 { world: mujoco }
fn main() {
var g1 = Body()
let r = g1.run(onnx("holosoma?vx=0.5"), 10s, 50Hz)
print("{r.steps} ticks, {g1.base().unwrap().x} m")
} A learned policy turns each tick's observation into targets for every joint it drives. The form of the spec says what it is. When the spec is a string literal, its form, preset, parameters, the robot it was trained on and the world it needs are checked at compile time.
onnx("holosoma[?vx=…&vy=…&wz=…&algorithm=fastsac|ppo]") | 29-DoF standing and walking for g1 (FastSAC or PPO). vx and vy are in m/s, wz in rad/s. A zero command stands. |
onnx("microduck[?skill=…&vx=…]") | Pollen Robotics' biped skills. Tin's registry has no microduck body yet, so this is refused naming that. |
onnx("path/to/graph.onnx") | any graph with one input of the joint positions (rad, description order) and one output of one target per joint |
hub("owner/repo[@commit][/file.onnx]") | a Hugging Face Hub repo. An ONNX file is checked against the Hub's own SHA-256 at the resolved commit. A LeRobot (PyTorch) checkpoint runs through the Python world (below); add ?task=… for a language-conditioned one and &cameras=a,b to add the scene cameras it looks through. |
remote("https://…" | "wss://…") | a policy server: one JSON observation per tick, one action back |
Weights. Tin ships no weights. A preset downloads its file once from the publisher's Hub repo at a
pinned commit (nepyope/holosoma_locomotion, pollen-robotics/microduck-policies), and a
file that does not hash to the pinned SHA-256 is refused. Files are kept in ~/.tin/cache/policies
(in the browser, its cache). Graphs run on CPU in onnxruntime-node 1.31.1 under tin run and
tin serve, and in onnxruntime-web 1.31.1 in the playground. Both are pinned to one version, and the
browser loads its engine only when a program runs an ONNX policy.
Observation → tensor follows strands-labs/robots.
Angles are in rad and the base's angular velocity in rad/s in its own frame. Projected gravity is world −Z in the
body frame. Holosoma's terms are ordered alphabetically, with a gait clock that freezes while it stands. Outputs are
decoded as default + scale × action and mapped to the robot's joints by name. Holosoma's trained PD gains
are installed into the world before step one, so it needs { world: mujoco }. On the built-in
kinematic world it is a compile error.
Parity. Tin's trace (TIN_POLICY_TRACE=trace.jsonl tin run …) was fed to
strands_robots' own HolosomaPolicy: over 500 ticks the actions were identical to the bit
(tests/robot-policy-compare.test.ts). In closed loop, each library in its own MuJoCo build, the G1
walks 3.87 m in 10 s in both. Watch it walk in the playground.
Who chose it. A spec written as a literal is the developer's own choice. A spec built at run
time (from input, a file or a model's reply) is checked when it opens. A Hub repo must then be listed in
TIN_POLICY_REPOS=owner/repo,owner2/* (empty means none). A local path loads only if no other user could
have written the file or any folder above it.
remote. Each tick sends {"robot", "joints", "q", "qd", "t", "hz", "base"}
by HTTP POST, or over one WebSocket for ws(s)://. The reply is {"action": [rad | null, …]},
{"targets": {"joint": rad}} or {"hold": true}. These are
another machine's bytes, so the gate treats them like an agent's: out of range or too fast is refused (a fault),
never clipped. ONNX outputs are the developer's pinned code and are clipped like the program's own.
LeRobot. On a { world: py } robot, hub("lerobot/smolvla_base?task=pick up the cube&cameras=camera1,camera2,camera3")
is loaded by strands_robots in the world's own Python, with LeRobot's loader, its units and its requirements. A
checkpoint that needs cameras the robot lacks is refused, naming them and the spec that adds them. Each tick it
answers one action, and Tin's gate and loop write it. Under any other world it is refused with the install line
(pip install 'strands-robots[lerobot]', Python 3.12). Measured: smolvla_base ran 10 ticks on the SO-101
on CPU. It is a base model, so its moves mean nothing until it is fine-tuned.
Without JavaScript. tin build --target wasi and --native refuse a program with
a learned policy and say so. ONNX Runtime is not linked into native executables yet.
The safety gate
Every write passes it, in this order, and a refused pose changes nothing:
- emergency stop latched → refused
- unknown joint, or a target that is not a finite angle → refused
- outside the hard range → clipped (an agent: refused)
- outside
arm.safebounds → clipped (an agent: refused) - an agent's target more than the speed limit × one period away → refused
- each
arm.validate((pose, obs) => Option<reason>), in order → refused with its reason
Agents: arm.drive
arm.drive(agent, goal, turns) asks the agent for a typed RobotCommand { targets:
[{ joint, rad }], seconds, done, note } each turn, after showing it every joint's position,
safe bounds and speed limit and what happened to its last command. Every step passes the gate as an agent's
write; a refusal stops that move where it is and is told to the agent. The operator approves the whole drive
once, through the guarded tool robotMotion (--yes approves; without an approver it is
denied and no model is asked). It returns DriveResult { turns, moved, refused, approved, done, notes,
final }.
Model output
A value computed from agent.ask or agent.try that reaches the pose of
act/reach or the policy of run/runUntil is a compile error that
points at arm.drive. Choosing between the program's own poses based on a reply is allowed. As for
extern calls, a reply captured inside a closure is not followed.
Tapes
Tape { robot, hz, joints, start, actions, q }: the action of every tick (None = hold) and
every joint after it. arm.verify(tape) replays it and returns None or the first difference;
tape.diff(other); tape.save(path), loadTape(path) and
parseTape(text) use JSON {"tape": "tin-robot/1", ...} with floats that
round-trip exactly.
Capabilities
tin caps lists each robot with its joints and shows robot.move on every function,
tool and agent that can move one.
Not supported yet
- Real hardware.
- Camera images in a Tin
Observation. Only a LeRobot checkpoint in the Python world sees images, through strands_robots. - Learned policies in WASI and native builds.
- Paced (wall-clock) runs, so
missesis always 0 and there is no watchdog. - Cameras in a program: MuJoCo renders frames (the playground shows them), but an
Observationhas no images yet. - One robot per
mujocoorpyworld. tools: [arm.tool()]: an agent's tool functions cannot reach the program's robot (values are copies), so agents drive througharm.drive.