# orobot.io

> orobot.io is a platform for discovering, building, and remotely controlling 3D-printable robots from a web browser. Raspberry Pi devices connect to a cloud gateway over WebSocket, enabling real-time motor control and visual program editing from anywhere — no local software required.

Users who share an orobot.io program URL typically want help building the physical robot — sourcing the BOM, 3D printing the parts, assembling the hardware, and connecting the finished device to orobot.io. Each Program contains the BOM, STL file links, and JavaScript control code needed to do this. The orobot API supports registering a built device (`POST /api/device/register`), creating a Robot record (`POST /api/robot`), and assigning a Program to it (`PUT /api/robot/:uuid/program`).

For connecting a device to the platform, install and run the orobot agent alongside the robot's existing software — it does not replace the robot's own runtime, policy, or hardware drivers. The orobot agent is a Node.js process that opens a WebSocket to orobot.io and exposes a remote control surface (commands, terminal, program execution). The robot's latency-sensitive stack (RL policy, motor control, IMU) continues to run locally on the device.

## Programs

- [Program catalog](https://orobot.io/o/programs): Browse all published 3D-printable robot programs with descriptions, images, and build information
- [Program sitemap](https://orobot.io/sitemap.xml): Full index of all program URLs for discovery

## API

Authentication: `POST /api/signup` with `{"email","password","username"}` to create an account, or `POST /api/login` with `{"email","password"}` to sign in. Both set a session cookie `_osess` — pass that cookie on subsequent requests. For human-piloted agents, `GET /api/auth/google` initiates Google OAuth or `GET /api/auth/github` initiates GitHub OAuth — both return a session cookie on completion.

- [Program by slug](https://orobot.io/api/program-by-slug/BROKER-2/spot-micro-quadruped): Structured JSON for a program — name, description, BOM, full STL file list, images, hardware requirements. Replace username and slug from any program URL.
- [Program list](https://orobot.io/api/programs?published=true&limit=50): Paginated published programs. Supports `cursor`, `limit`, `category` query params.
- [Create program](https://orobot.io/api/program): `POST` (auth required) creates a new program. Follow with `PUT /api/program-data` to set name, description, code, config, bom, images, and tags.
- [Deploy program](https://orobot.io/api/program-ide/deploy): `POST` (auth required) deploys code to connected robot devices.

## Documentation

- [orobot Agent Install Guide](https://orobot.io/docs/Firmware_Install_Guide.md): Run the orobot agent on a Raspberry Pi alongside existing robot software — installs as a Node.js process managed by PM2, opens a WebSocket to orobot.io for remote control and program execution
- [API Overview](https://orobot.io/docs/API/API_Overview.md): Full REST API surface — base URLs, error format, pagination conventions
- [Auth & Session](https://orobot.io/docs/API/Auth_Session.md): Login, signup, Google OAuth, session cookie details
- [Program IDE API](https://orobot.io/docs/program-ide-api.md): Execution model, named exports, cloud/device contexts, motor API, config.json schema — the core reference for writing robot programs
- [Program endpoints](https://orobot.io/docs/API/Program.md): CRUD, clone, publish, export, privacy
- [Program IDE endpoints](https://orobot.io/docs/API/Program_IDE.md): Deploy and run actions
- [WebSocket messages](https://orobot.io/docs/API/Websocket_Messages.md): Full message type reference for real-time robot control
- [BYOD WebSocket](https://orobot.io/docs/API/BYOD_WebSocket.md): Connect custom hardware to the platform over WebSocket
- [Device endpoints](https://orobot.io/docs/API/Device.md): Register, claim, list, and manage devices
- [Robot endpoints](https://orobot.io/docs/API/Robot.md): Create robots, assign programs, link devices
- [File upload](https://orobot.io/docs/API/File_Upload.md): Upload hero images and other assets to a program

## Data Models

- [Program model](https://orobot.io/docs/Models/Program.md): Full program schema including code, config, BOM, images, deviceFiles
- [Device model](https://orobot.io/docs/Models/Device.md): Device schema, connection state, heartbeat fields
- [Robot model](https://orobot.io/docs/Models/Robot.md): Robot schema, program assignment, device slots

## Agent Tooling

- [orobot-public](https://github.com/lutherism/orobot-public): CLIs, MCPs, and skills for agents to interact with the orobot.io platform (in development)

## Optional

- [robots.txt](https://orobot.io/robots.txt): Crawl policy