botblocks
projectsgalleryworkspacedocsprofile
introdemospythondashboardcli

botblocks

botblocks is a rapid-prototyping stack for robots. a python script defines the world and robot behavior; a workspace lets you run it, inspect the scene, and work with an agent.

the stack is built around four small ideas:

  • a Robot is loaded from a project path such as public/so101 or menagerie/unitree_go2
  • named subsystems such as Servo, Arm, Camera, and DiffDrive are the robot api
  • providers connect those subsystems to mujoco, a kinematic viewer, or local devices
  • the workspace combines the editor, 3d viewer, console, camera snaps, inspector, agent, and rl metrics

run a robot in physics

open a robot from the gallery, or paste this into the workspace and press run:

from botblocks import Box, MujocoEnv, Plane, Robot
import math

robot = Robot().load('public/so101')
cube = Box(pos=[0.28, -0.12, 0], size=0.03, color='#f8a')

@robot.loop
def wave(bot, env):
    bot['shoulder'].target(0.35 * math.sin(env.time()))

MujocoEnv([Plane(), cube, robot]).start()

MujocoEnv simulates gravity, contacts, sensors, and actuators. open the inspector to drive joints, or ask the agent to list and call the live subsystem tools. the console shows script output; camera snapshots and numeric metrics have their own panels.

to run the script on your machine, follow the cli setup and use botblocks run script.py. demos cover manipulation, keyboard controls, and policy training.

change the backend

use ViewerEnv when you only need fast kinematic poses and camera previews:

from botblocks import ViewerEnv

ViewerEnv([Plane(), robot]).start()

LocalEnv runs with device providers on your machine. see the hardware providers section of the python api for the interface and current adapter limitations.

bring your own robot

the gallery contains the mujoco menagerie. projects store robot definitions and assets. import a robot, edit its part tree and subsystems, then load it as Robot('project/name'). arm kinematics are inferred from the same geometry used by the simulator and viewer.

external agents

connect an mcp client to https://botblocks.dev/mcp and complete the browser sign-in. a local host exposes http://localhost:6675/mcp.

start with proc_create or proc_connect. use subsystem_list to discover exact tool names and arguments, then subsystem_call to operate the robot. script edits take effect after script_deploy. pass proc and env handles explicitly when more than one exists; the mcp is stateless. its docs tool serves sections from these same pages.