# For AI agents

> A quick orientation for coding agents and language models building against RosieOS, covering where the machine-readable docs and specs are, the interfaces to use and the safety rules to respect.

URL: https://advancedmetalresearch.com/docs/get-started/for-ai-agents
Section: RosieOS docs / Get started
Last updated: 2026-10-10

This page is for coding agents, assistants and retrieval pipelines that read these docs or write code against RosieOS. Everything here is a summary of other pages. When a detail matters, follow the link and read that page.

## Robot data and downloads

The URDF, MuJoCo model, SRDF, STEP, meshes and `robot.json` of the Rosie 600, 1000 and 1400 are static files with stable URLs. [`/agents.md`](/agents.md) is the step-by-step guide to fetching them, with copy-paste curl, Python and JavaScript and a link to every file. [`/agents.json`](/agents.json) is the same list as JSON, and [`/assets/sim/index.json`](/assets/sim/index.json) lists every kit file.

- Plain HTTPS GET or HEAD: no login, no API key, no cookies.
- Any User-Agent works, including the defaults of Python `urllib`, `requests`, Node `fetch`, Go, curl and wget.
- CORS is open (`Access-Control-Allow-Origin: *`) on the data files, so a web page can load the JSON, URDF, STL and GLB files directly.
- Byte ranges and ETag revalidation work.
- The URDF and MJCF use relative mesh paths, so they load from their URL or from the unzipped kit.

If your environment cannot reach advancedmetalresearch.com, use the mirror on GitHub, [advanced-metal-research/rosie-sim-kits](https://github.com/advanced-metal-research/rosie-sim-kits). The same files are at `https://raw.githubusercontent.com/advanced-metal-research/rosie-sim-kits/main/sim/...`, and its `sim/index.json` lists them with mirror URLs. Failing that, ask your user to download the kit ZIP and attach it. Every file is inside it.

## Read the docs as data

| What | Where | Contents |
|---|---|---|
| Site index | [`/llms.txt`](/llms.txt) | Every page with a one-line description, in the llmstxt.org format |
| RosieOS docs index | [`/docs/llms.txt`](/docs/llms.txt) | The docs section on its own |
| Full text | [`/docs/llms-full.txt`](/docs/llms-full.txt), [`/llms-full.txt`](/llms-full.txt) | Every docs page (or the whole site) as one Markdown file |
| One page as Markdown | Add `.md` to the page URL: `/docs/concepts/architecture.md`, and `/docs/index.md` for the docs home. A request with `Accept: text/markdown` gets the same file. | The page source, with links made absolute and its source files listed. Each page also has *View as Markdown* and *Copy page* controls. |
| Agent guide | [`/agents.md`](/agents.md), [`/agents.json`](/agents.json) | How to fetch the robot data, and every data file, API spec and guide with its URL |
| Search index | [`/assets/docs/search.json`](/assets/docs/search.json) | Title, section, URL, Markdown URL, description, headings and text of every page |
| rt-control API | [OpenAPI 3.1](https://advancedmetalresearch.com/docs/openapi/rt-control.json), [original contract](https://advancedmetalresearch.com/docs/openapi/rt-control.contract.json) | Generated from `rt-core/protocol/application-v1.schema.json` |
| API catalog | [`/.well-known/api-catalog`](/.well-known/api-catalog) | The rt-control, offline programming and weld planner HTTP APIs and their OpenAPI files, as an RFC 9727 linkset |
| Other HTTP APIs | [Offline programming](https://advancedmetalresearch.com/docs/openapi/offline-programming.json), [weld planner](https://advancedmetalresearch.com/docs/openapi/weld-planner.json) | OpenAPI 3.1, generated from their reference pages |
| Error codes | [`/docs/data/error-codes.json`](/docs/data/error-codes.json) | All 153 rt-control reasons, with meaning, group, HTTP status and callers |
| NATS | [`/docs/data/nats-subjects.json`](/docs/data/nats-subjects.json) | Subjects, streams and the command tables |
| Robot models | [`/assets/sim/index.json`](/assets/sim/index.json) | URDF, MuJoCo, STEP and `robot.json` of the Rosie 600, 1000 and 1400, with every file's URL. See [Simulate a Rosie robot](https://advancedmetalresearch.com/docs/guides/simulate-a-rosie-robot). |

## The system in brief

- **One public control API.** Every client drives the robot through [`rt-control`](/docs/apis/rt-control-http). That includes the pendant, offline programming (OLP), the motion servers and your code. It serves HTTP/JSON on the Unix socket `/run/rosie-rt-core/control.sock`, and optionally over mutual TLS on `127.0.0.1:8443` for [remote clients](https://advancedmetalresearch.com/docs/apis/remote-access-mtls). Behind it, the 1 kHz [real-time core](https://advancedmetalresearch.com/docs/concepts/real-time-core) owns the EtherCAT drives. See [Architecture](https://advancedmetalresearch.com/docs/concepts/architecture).
- **One controller at a time.** `acquire` returns a fence: a session token and a generation, under an expiring lease. Every later command carries that exact fence. Renew before the lease runs out. A second client gets `control_already_owned`. See [Control authority](https://advancedmetalresearch.com/docs/concepts/control-authority).
- **Three kinds of motion request.** Jog (`begin_jog`, datagrams on `jog.sock`, `end_jog`), trajectories (`prepare_trajectory`, `start_trajectory`) and programs (`prepare_program` with a [`.rdt` file](/docs/reference/rdt-format), then `start_program`). The [motion paths](https://advancedmetalresearch.com/docs/concepts/motion-and-planning) page says which process owns each path.
- **Clients.** The [Go SDK](https://advancedmetalresearch.com/docs/apis/go-sdk), the header-only [C++ client](https://advancedmetalresearch.com/docs/apis/cpp-client), [TypeScript contracts](https://advancedmetalresearch.com/docs/apis/typescript-types) (types only, no HTTP client) and the [`rtctl`](/docs/reference/rtctl) CLI.
- **Other services.** The [OLP server](https://advancedmetalresearch.com/docs/apis/olp-http) on `127.0.0.1:8794` and the [weld planner](https://advancedmetalresearch.com/docs/apis/weld-planner-http) on port 8796. The planner listens on all interfaces by default. Neither has authentication. Every port and socket is listed in [Ports and environment](https://advancedmetalresearch.com/docs/reference/ports-and-environment).
- **Formats.** [`robot.v4.program.v2`](/docs/reference/program-format) programs, the [`.weldplan`](/docs/reference/weld-program-format) plan request, [`.rdt`](/docs/reference/rdt-format) dense trajectories, and [robot description](https://advancedmetalresearch.com/docs/reference/robot-description) and [configuration](https://advancedmetalresearch.com/docs/reference/configuration) files.

## Safety rules you must respect

Read the [safety model](https://advancedmetalresearch.com/docs/get-started/safety-model) before you write code that moves hardware. In short:

- **There is no software E-stop.** RosieOS contains no safety-rated function. The cell's hardware E-stop and safety chain are the only emergency stop. Stop, Halt, lease expiry and the pendant's hold-to-enable trigger are software functions, and they can fail with the software that runs them.
- **Only planned weld programs are verified.** A weld program is admitted at OLP Load only if the weld planner's collision, limit and tracking certificate passes. Jog, moves and Home are checked against joint limits only, not against collisions.
- **Torch outputs are refused everywhere.** RosieOS does not switch a welding torch. No seam tracking or sensing is implemented; see [Process I/O and sensing](https://advancedmetalresearch.com/docs/concepts/process-io-and-sensing).
- **Simulation does not qualify hardware.**
- **Claim only what the safety model allows.** It gives the exact sentence you may use about program verification.

## Rules of thumb for code

- The server decodes strictly. Unknown fields, duplicate fields and trailing data are refused.
- Put a `request_id` on JSON commands so that you can retry them safely, and use a fresh one for every logical attempt. `/v1/program` uploads have no deduplication: never replay an uncertain upload. See [idempotent retries](https://advancedmetalresearch.com/docs/apis/rt-control-http#idempotent-retries).
- Refusals are HTTP 409 with a reason in `error` (413 for an oversized body). Match on the leading label. Treat an unknown label, a malformed reply or a transport failure as an unknown outcome. Stop producing motion, send an authenticated `stop` if you can, and reconcile Status before you acquire again. See [Error codes](https://advancedmetalresearch.com/docs/reference/error-codes).
- A 200 reply for motion acknowledges admission, not physical completion. Follow [events and telemetry](https://advancedmetalresearch.com/docs/apis/rt-control-events-telemetry) to see what happened.
- Keep uint64 values exact. In TypeScript they exceed the safe integer range.

## Where to find things

| Task | Page |
|---|---|
| Run a whole cell on one machine | [Run everything in simulation](https://advancedmetalresearch.com/docs/guides/run-in-simulation) |
| Load a Rosie robot into PyBullet, MuJoCo, ROS 2 or CAD | [Simulate a Rosie robot](https://advancedmetalresearch.com/docs/guides/simulate-a-rosie-robot) |
| First program against the core | [Your first motion](https://advancedmetalresearch.com/docs/get-started/first-motion) |
| Every rt-control operation, type and reason | [rt-control HTTP API](https://advancedmetalresearch.com/docs/apis/rt-control-http) |
| Plan and run a weld from CAD | [Program a weld from CAD](https://advancedmetalresearch.com/docs/guides/offline-programming), [Connect to a cell](https://advancedmetalresearch.com/docs/guides/connect-a-cell) |
| Mount a tool or the robot | [Mechanical interfaces](https://advancedmetalresearch.com/docs/reference/mechanical-interfaces) |
| Repository layout and generated files | [Repository layout](https://advancedmetalresearch.com/docs/contributing/repo-layout) |

## Sources

Written from these files in the RosieOS repository (https://github.com/advanced-metal-research/RosieOS):

- `src/docs/get-started/safety-model.md`
- `src/docs/concepts/architecture.md`
- `src/docs/concepts/control-authority.md`
- `src/docs/concepts/motion-and-planning.md`
- `src/docs/concepts/process-io-and-sensing.md`
- `src/docs/apis/rt-control-http.md`
- `src/docs/apis/typescript-types.md`
- `src/docs/reference/error-codes.md`
- `src/docs/reference/ports-and-environment.md`