Developers

The Waddle Stack

This is a brief sketch of how an agent operates inside Waddle, some tools it has access to, and how we achieve hardware agnosticism through the stack.

The Waddle stack is constructed from three hierarchical layers. From hardware to agent, in increasing layers of abstraction:

1
waddle-sdk is the public-facing layer that defines hardware contracts for higher-level Waddle consumption. It handles all communication with hardware (motors, cameras, sensors) and abstracts across different hardware specifications to provide a unified API for waddle-metal to consume.
Examples
Enforcing the hardware safety envelope, capping joint speed limits, sending joint angles to motors, and reading from cameras.
2
waddle-metal uses waddle-sdk primitives to define skills that allow for local code execution using the Waddle stack. This is the layer where most of the tools are built.
Examples
Inverse kinematics solvers, trajectory planning, object segmentation, and moving a robot arm to a 3D pose.
3
waddle is our closed-source server for hosting the agent harness. It routes models, builds a closed-loop environment for agentic reasoning, and handles context management.
Examples
Sub-agent orchestration, MCP tools, skills library, compaction, reading / writing / running waddle-metal code.

See the FAQs below for a more intuitive schematic.

Core design principles

Extensibility

Each layer in waddle-sdk and waddle-metal defines contracts and conventions with reference implementations, but allows users to extend them with custom hardware and software as long as the conventions are respected. For example:

Waddle provides reference backends for YAMs, Alicia arms, and the xArm 7.
Anyone can port custom hardware to waddle-sdk. We define protocols for what we expect an arm or a camera to supply; users adapt those protocols to their specific hardware.
waddle-metal ships with a default IK solver, but our design partners with access to waddle-metal can customize the inverse kinematics solver for particular hardware embodiments.

Graceful degradation

The Waddle stack defines explicit capability matrices that are consumed downstream, allowing for graceful degradation based on what is available lower down in the stack. For example, if waddle-sdk does not declare depth information for a particular camera embodiment, that is ingested by waddle-metal and waddle. The agent is restricted to tools available with RGB—such as visual masking and object bounding boxes—instead of failing repeatedly on depth-enabled tools such as point clouds.

FAQs

Why does this work?

Consider a loose analogy to LLVM.

A simplified LLVM stack, with language-specific frontends feeding a language- and hardware-agnostic optimizer that targets instruction-set-specific backends. — Fig. 1 — A greatly simplified schematic of the LLVM stack.

The Waddle stack, with model adapters feeding the Waddle harness and waddle-metal intermediate representation, which targets hardware-specific robot backends. — Fig. 1 — A greatly simplified schematic of the LLVM stack.

We like to draw a loose analogy between Waddle's stack and LLVM. Just as LLVM enables the same programming-language frontend to work across different hardware instruction sets, Waddle enables agents to work identically across different hardware. The key is a hardware-agnostic intermediate representation (IR).

Take LLVM and Rust, for example. By choosing to compile into LLVM IR instead of specific assembly code, the Rust language compiler automatically works across most common instruction sets without additional code.
Similarly, Waddle has a proprietary IR that we call waddle-metal. waddle-metal exposes unified tools such as inverse kinematics, path planning, and grasp sampling for agents to use. During execution, these higher-level methods dispatch into hardware-specific implementations provided by waddle-sdk, achieving hardware agnosticism.
The Waddle harness constructs a closed-loop environment for agents to interact with the real world using waddle-metal. Agents write the same code and use the same tools regardless of hardware.

What does it take to port new hardware?

Not much. For a robot arm, the hardware-specific implementation required by waddle-sdk is small:

A declaration of the robot kind and estopped status;
read() for joint position and velocity;
write(target) for driving to desired joint positions;
hold(), estop(), and re_enable() functions;
home(pose) to reset the arm during operation, and a deterministic close() to put the arm in its resting position before shutting down.

Optional implementations unlock more of waddle-metal's capability matrix:

write_position_velocity(...) enables known velocity feed-forward control;
Adding a valid URDF file enables forward and inverse kinematics and path planning in waddle-metal;
Body collision spheres enable collision-aware safety checks;
A gripper declaration enables gripper control.

For a camera, CameraDriver needs only define a capture() → CameraFrame function to capture frames and a close() function that releases the stream for other processes. A depth array may also be declared per frame for depth-enabled cameras.