# Set up your Mac for Roboty

Keep the selected workspace available and connect through its normal owner.

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

## With an installed companion

Open Roboty on the Mac. In **Settings → iPhone Connection**, read its availability status. Keep the Mac awake and logged in. If availability is off, choose **Enable availability**. Choose **Pair iPhone** when you want the phone interface. Open Connect a computer on the phone and review the invitation for this Mac.

In Workspace, click the experiment name in the header to rename it. The task, robot and simulation location remain visible beside the name. The Goal inspector groups Task, Position and Success, with Movement method behind a disclosure. It sits beside the diagram in a wide window and follows below it in a narrow window.

Forward (X), Left (Y) and Height (Z) are editable in centimetres. Their + and − buttons adjust by 1 cm. Click or drag the map to edit the same selected destination. For a waypoint, choose Waypoint first or Final target. For Cube to tray, choose Cube start or Tray destination. Their scene heights stay fixed. Saved geometry keeps its exact metre values.

Use **Hide inspector** for more diagram space and **Show inspector** to return to the fields. Undo and Redo sit beside Destination. Save stays in the toolbar with its status and any blocking reason beside it. If the workspace is closed, choose **Open workspace** before saving. If secure storage needs permission, choose **Authorize secure storage** in the same action area. A locally retained draft is separate from a confirmed saved version. **Preview goal** inspects the saved geometry. Start remains a separate confirmed action. The diagram does not prove reachability.

Use the toolbar's contextual Ask and Help controls for the selected goal or result. Select the compact simulation status indicator for the current reason and recovery actions.

Open Roboty Help from the Help menu. Help opens in the main content area. Choose **Back to your task** to return to your work. Search Help searches the bundled instructions, not your private experiments or results. Getting-started actions return you to Workspace or Settings when the step needs those controls. Opening a guide never starts an experiment.

You can open and use the Mac's local workspace without enabling background availability. For the installed app's phone-connection setup, choose **Enable availability** and follow any macOS approval. Enabled background hosting continues after the window closes or the app quits while the Mac stays awake and you are logged in. **Stop background hosting and quit…**, pausing or disabling availability can interrupt work. Read the confirmation, then check the same attempt's status before starting another.

For a supported arm, choose **Robots** in the sidebar or **Home → Add a robot**. Use the sidebar to return to Home or Projects. Connection review saves existing robot facts, controller
profiles and original calibration separately from simulation. Follow [Add a supported
robot](/guide/setup/physical-robot) for the setup order, current blockers and
original-action recovery. Pairing a phone does not grant hardware access. Roboty manages its runtime internally. Roboty operation requires no separate Python, conda or LeLab installation, ChatGPT login or AI provider setup. A phone is optional. Suppliers own assembly, firmware servicing and repair. Roboty handles supported necessary software configuration and calibration. Preserve the supplier sequence when motor IDs are configured during assembly. Stop/reconcile the original session before another tool owns a board. A missing or incompatible Roboty hardware component needs a matching Roboty for Mac build from the installation maintainer. Keep upstream software separate from that component.

In **Robots**, select a saved physical robot in the list, or choose **Add a robot** to connect another. Its page shows setup and connection status with one next action. **Review connection requirements**, **Check connection**, **Test & practice** and maintenance remain available below. **Rename robot** is beside its identity. **Save robot details** saves the name and any current setup changes. A project is optional. Reusable configurations, tasks, methods and scenes live in **Library**. Save the controller profile, then use **Review this connection session on this Mac…** for one finite session. Roboty temporarily pauses its host, requests local authentication, restores the previous availability choice and reconnects. You do not need to manually manage background hosting for normal review. Setup verifies configuration and calibration before separately admitted practice. Supported initialization and calibration use their own finite local review. They retain observations without marking the robot fully verified. Supervised setup is enabled in this development build. Each physical session still needs your explicit local review. Routine hardware verification and measured physical acceptance remain separate. See [Add a supported robot](/guide/setup/physical-robot) for the exact sequence and original-session recovery.

In Workspace, **Import file…** opens a project, reusable setup, experiment or mixed selected file for review. Choose one supported item from a mixed file, then complete its usual import review. An imported setup may need local ingredients or a compatible runtime before it can be prepared. Import does not install dependencies or start an attempt. See [selected sharing](/guide/use/sharing) for what a file may contain.

## Explore more: development checkout

Use the clean Roboty checkout and its pinned tools. The repository requires the supported Node version, Corepack/pnpm and uv. Install dependencies and check the host before starting it:

```sh
bash scripts/with-runtime corepack pnpm install --frozen-lockfile
uv sync --locked --project apps/workbench
bash scripts/with-runtime corepack pnpm workbench:bootstrap
bash scripts/with-runtime corepack pnpm workbench:native:doctor
bash scripts/with-runtime corepack pnpm workbench:native:start
```

The foreground launcher owns the local workbench and native listener. Keep its terminal open. Startup does not start an experiment or qualify a profile. Do not start another owner against the same store or terminate an unrelated process to free a port.

To create a private pairing invitation through the existing owner:

```sh
bash scripts/with-runtime corepack pnpm workbench:native:admin pair --port 8766
```

The command gives a private QR path to open locally. Keep invitations out of screenshots, public posts and agent prompts. On the phone, use Connect a computer and inspect the intended Mac before approving it.

## Confirm the selected workspace

Choose that Mac's workspace before editing the tutorial goal. Phone-local and Mac workspaces keep different drafts and results. Connecting does not move an existing goal. Keep local work or use the explicit supported transfer workflow.

## If connection fails

If Open workspace reports that secure storage needs authorization, choose
**Authorize secure storage** to review the Mac's permission dialog deliberately.
Unlock the Mac first when storage is locked. If you deny or cancel, your original
key and saved work remain intact. Do not delete the key or reset pairing to bypass
the error. A dialog naming a different application or signing key needs its own
identified requester.

Check the selected Mac, host status, wake/login state and network route. Read Local networks and Tailscale for guest-network and remote-access issues. Keep your draft. If an attempt is uncertain, reconcile its original identity instead of starting a replacement.

## When simulation is unavailable

The Workspace names the selected simulation and explains whether it is unsupported, not yet verified or not enabled for this Mac setup. Choose **Check availability** beside the message to refresh support. **Availability details** shows the reported reason. You can keep editing and saving while you resolve the reported setup requirement.

Use [Add a supported robot](/guide/setup/physical-robot#choose-the-experience) for necessary software configuration and calibration on the owning Mac. Suppliers retain assembly, firmware servicing and repairs. Preserve their assembly sequence and the optional [note from Gabe](/guide/setup/physical-robot#founder-assembly-resources). Each hardware action needs its own current local review. Powered commissioning remains separately qualified.

Content ID: mac-setup
Compiled digest: 9f6ec5703e9247edb92e59d792b14474cac6093c0fa0c9a19ec7a7b33385d682
Language: en