Tin
Reference · Robots

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.

idaliasesjoints
so101robotstudio_so101, so101_follower, so_arm101shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper
so100trs_so_arm100, so100_follower, so_arm100Rotation, Pitch, Elbow, Wrist_Pitch, Wrist_Roll, Jaw
pandafranka_panda, franka_emika_pandajoint1, joint2, joint3, joint4, joint5, joint6, joint7
ur5euniversal_robots_ur5eshoulder_pan_joint, shoulder_lift_joint, elbow_joint, wrist_1_joint, wrist_2_joint, wrist_3_joint
unitree_go2go2FL_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_g1g1left_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
stretch3hello_robot_stretch_3, stretch_3joint_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() { }
WorldRuns onWhat moves the joints
kinevery hostTin: each joint a first-order servo (40 ms) within its speed and range, 2 ms steps. Not physics: no gravity, contacts or dynamics.
mujocotin run, the playground, nativeMuJoCo 4.0.1, Google DeepMind's WebAssembly build (@mujoco/mujoco, optional): gravity, contacts, the robot's own actuators.
pytin runThe 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:

  1. emergency stop latched → refused
  2. unknown joint, or a target that is not a finite angle → refused
  3. outside the hard range → clipped (an agent: refused)
  4. outside arm.safe bounds → clipped (an agent: refused)
  5. an agent's target more than the speed limit × one period away → refused
  6. 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 misses is always 0 and there is no watchdog.
  • Cameras in a program: MuJoCo renders frames (the playground shows them), but an Observation has no images yet.
  • One robot per mujoco or py world.
  • tools: [arm.tool()]: an agent's tool functions cannot reach the program's robot (values are copies), so agents drive through arm.drive.