# Prepare a development installation

Use the repository runtime and native build owners when no public installer exists.

Canonical: https://roboty.dev/guide/setup/developer
Content revision: 7
Platforms: iphone, mac, browser, agent

## Before you start

This path is for contributors with the Roboty repository on a Mac, Xcode and its command-line tools, Git, and the repository's pinned Node/pnpm and uv/Python setup. Use your own workspace and Apple signing identity. Public native downloads remain unavailable. [Learning](/guide/learn) needs none of these prerequisites.

## Prepare the repository

From the repository root, use the pinned wrapper for each shell command:

```sh
bash scripts/with-runtime corepack pnpm install --frozen-lockfile
bash scripts/with-runtime uv python install --no-bin "$(cat apps/workbench/.python-version)"
bash scripts/with-runtime uv sync --locked --project apps/workbench
```

Native preparation selects the already installed Python matching the Workbench pin, checks safe archive extraction, and refuses a missing interpreter before building. It does not download Python during a build or use the system Python as a fallback.

The wrapper checks the pinned runtime. Read the repository's `docs/README.md` and `docs/ios.md` for current machine/signing prerequisites and the existing prepare/install owners. A missing runtime must be installed through that supported setup rather than changing pins.

## Choose a surface

- Website Help: `bash scripts/with-runtime corepack pnpm dev` uses the primary checkout at port 3200. It does not start a robot host.
- iPhone source compile: `bash scripts/with-runtime corepack pnpm ios:compile`. Compilation is not installation or a qualified device simulation route. Follow the connected-device runbook for your own explicitly chosen development installation. Retain an existing app/container.
- Mac host or headless agent: follow [Mac setup](/guide/setup/mac) or [the staged agent workflow](/guide/use/your-agent). The host owns private records and current readiness.

After installation, [choose the workspace](/guide/setup/devices) and [enter the first tutorial](/guide/get-started/simulation/route). Public distribution and physical robot operation are not enabled by a development installation.
The normal Mac packaging owner includes Roboty’s separately pinned hardware component automatically. A missing or incompatible component requires a matching Roboty build through `docs/workbench.md` → Runtime and data preparation. No end-user dependency installation or hardware build flag is needed. Keep the separate runtime and compiled-asset/signing boundaries. A bundled component does not qualify physical operation. The optional [standalone upstream reference](/guide/setup/so101-software) is outside the default setup and recovery path. [Roboty setup](/guide/setup/physical-robot#choose-the-experience) names current readiness and original-operation recovery.

Interactive Mac builds require `--purpose interactive`, an existing verified
Apple Development identity on Roboty's configured team, and an existing reviewed
compiled Reach asset bundle selected with `--compiled-reach`. The build validates
the selected bundle against its pinned engine, assets and template before creating
the app output. This reuses the selected model without generating a new one. Use `--purpose inert` only
for artifacts that do not access retained workspace credentials or register a
service. Keep the same development identity for successive interactive builds,
changing ad hoc identities can cause repeated secure-storage approval prompts.

## Connect an agent to local Help

With the local website running, append `/help/mcp` to its actual origin. For the
normal development address, this is `http://127.0.0.1:3200/help/mcp`. Use the port
shown by your server if it differs. This read-only documentation endpoint is
separate from the private Roboty host and its operating-agent interface.

`127.0.0.1` and `localhost` refer to the computer running the client. A client on
another computer or in the cloud cannot reach your Mac through that address.
Use the [Markdown exports](/guide/agents#read-documentation) when the client cannot
reach the local site. Do not expose or tunnel a private Roboty host to share Help.

Content ID: developer-setup
Compiled digest: 7e1c266a04a5e47ac9913394df117845eb287dd2163bf58fc29b891f2206abaa
Language: en