Prepare a development installation

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 needs none of these prerequisites.

Prepare the repository

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

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 or the staged agent workflow. The host owns private records and current readiness.

After installation, choose the workspace and enter the first tutorial. 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 is outside the default setup and recovery path. Roboty setup 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 when the client cannot reach the local site. Do not expose or tunnel a private Roboty host to share Help.