# Help for your agent Read the same approved instructions without product enrollment or robot access. Canonical: https://roboty.dev/guide/agents Content revision: 3 Platforms: iphone, mac, browser, agent ## Read documentation Start with [the page index](/guide/llms.txt) or [all public Markdown](/guide/llms-full.txt). Every article has a Markdown export. If your agent cannot connect to the website, give it the exported Markdown instead. ## Connect documentation MCP The canonical Streamable HTTP endpoint is `https://roboty.dev/help/mcp`. Public MCP access is not yet available. Use the Markdown links above for now. Repository contributors can [connect to local documentation during development](/guide/setup/developer#connect-an-agent-to-local-help). The read-only tools are `list_pages`, `get_page` with a known public page URL, and `search` with a query and optional surface filter. They search approved instructions, never private records, accounts, credentials or calibration. Broader search matches are explicitly labelled. ## Product access is separate [Follow the operating-agent wizard](/guide/get-started/agent/docs) or [read its continuous guide](/guide/use/your-agent) for an optional developer integration. Its example ends with a saved, read and prepared experiment, with zero simulations. The existing local host requires owner-reviewed enrollment and finite delegation. Review any disclosure to the client's model or host before allowing transmission. Documentation access grants no product, provider, simulation or physical authority. Content ID: agent-docs Compiled digest: 9a8ca8b3e43a97c57cbdb9470108913940f9212b41078b17ea303c3e87a8f32e Language: en --- # SO-101 assembly resources Gabe’s assembly video, supplier guidance and the next step into Roboty setup. Canonical: https://roboty.dev/guide/setup/assembly-resources Content revision: 3 Platforms: iphone, mac, browser, agent ## Haven’t assembled your robot yet? Start with the instructions supplied for your exact kit, including its wiring, power supply and assembly order. SO-101 kits can differ. Some require motor IDs to be configured before final assembly. Roboty can save a kit in progress and help with supported follower motor configuration. Mechanical assembly, firmware servicing and repairs remain with your supplier. An already-assembled arm can start software setup without repeating assembly. ## Gabe’s assembly video This is the video Gabe selected while assembling his own SO-101. It is a personal reference to use alongside your kit’s instructions. [Watch the assembly video](https://www.youtube.com/watch?v=mFnJjWp-K-A) The video needs internet access. This written page is also available in Roboty’s offline Help. ## More resources coming soon Gabe is collecting more resources from his own build. They will appear here after they have been selected and reviewed for the relevant kit. The existing video remains available above. ## Continue in Roboty On your Mac, open **Robots → Add a robot**. Choose your kit and assembly state, then review and save the robot. An unknown kit or assembly state can be saved for later, with identification as its next task. Motor settings and calibration are addressed when they become relevant. For an unfinished kit, the sequence follows your supplier’s order: choose the USB controller, configure motor IDs if needed, finish assembly, check all six joints and review calibration. An assembled arm skips assembly and starts with inspection when its motor settings are unknown. The [full setup guide](/guide/setup/physical-robot) explains each step. Development access remains invitation-only, and powered procedures require their own Mac review. ## Official visual reference The [official LeRobot SO-101 guide](https://huggingface.co/docs/lerobot/en/so101) includes assembly and calibration visuals. Check its applicability with your supplier. Use Roboty’s own controls for Roboty setup sessions. The upstream software commands are a separate workflow. Content ID: assembly-resources Compiled digest: 0597bf5502a61b3ea6db26481d44c38ed189fdb594551173b6d75a9eae39909f Language: en --- # Ask Roboty Ask about a goal, understand a result and choose what to try next. Canonical: https://roboty.dev/guide/use/ask-roboty Content revision: 2 Platforms: iphone, mac, browser ## When to use it Ask Roboty to explain a result, explore a goal or help you decide what to try next. Check the named work before sending your question. Changing screens does not change the discussion’s context. ## Assistant on Mac 1. Open **Settings → AI**. Choose **Continue with ChatGPT** and finish sign-in in this Mac’s browser. Choose **Check ChatGPT models**, select a model, then **Use ChatGPT connection**. API keys are not required for this route. 2. Under **Replies**, choose the connection to use. Return to your work and choose **Ask about this goal**, **Explain this result** or **Ask about compatibility** for a saved setup. 3. When the connection is ready, open **Review reply access**. Review the selected work and **Reply limits**, then choose **Allow replies**. 4. Type your question and choose **Ask**. **Open discussed result** returns to that attempt with assistance still open. Elsewhere, **Ask Roboty** or **Shift-Command-A** opens the panel. Closing it keeps your question. For an unsaved goal, the discussion uses a snapshot; later edits do not change it. Choose **Update to current goal** in Conversation options when needed, after finishing or stopping a pending answer. If you opened AI settings from assistance, **Back to your experiment** restores the panel and question. Voice input and spoken replies are not available on Mac. ## Assistant connection and usage On iPhone, open **Discussion** from the workspace. The selected Mac manages the connection. Choose **Check ChatGPT connection**, select a model, then **Use ChatGPT connection**. Finish sign-in on that Mac; the phone cannot complete its browser callback. Review reply access before asking. ChatGPT sign-in eligibility is unconfirmed. Follow the connection’s readiness message; signing in alone does not make replies available. Questions and local work remain saved when replies are unavailable. For connection and sleep problems, read [Keep your Mac available](/guide/troubleshooting/mac-availability). ## ChatGPT account on Mac If Roboty cannot read the saved connection, choose **Allow Roboty companion access** on the Mac and confirm Keychain access if prompted. This gives Roboty’s signed companion access to Roboty’s connection for Mac and paired-iPhone replies. Credentials stay on the Mac. Choose **Reconnect** for an expired or revoked connection, or **Reconnect saved account** after sign-out. Review connection and reply access again after reconnecting or changing accounts. Sign-out keeps discussions and experiments. If remote revocation could not be confirmed, disconnect Roboty in ChatGPT Settings. **Settings → AI → Developer API access** is a separate connection option. Saving a key does not permit requests. ## Reply access and usage Before **Allow replies**, review what will be shared and the usage limits. Follow-ups and ordinary explanations use the same allowance. Usage may be unknown while an answer is pending. **Manage ChatGPT usage and access** opens your account’s controls. If access expires or runs out, open **Review reply access** again. Your draft stays available. Allowing replies does not permit edits, simulations or robot movement. ## Keep the whole question Questions support 8,000 characters. A longer paste stays in your draft; shorten it before **Ask** or saving a browser question. Roboty does not silently cut off the ending. ## Questions in the Workbench browser In the Mac’s Workbench browser, **Save question locally** saves without asking an AI provider. For an answer, choose **Prepare an explanation**, review the recipient, selected work and usage limits, then approve the proposal. **Execute exact approved proposal** sends that request. **Attach image** and **Voice** are optional. Image review separates saving locally from sharing with a provider. If a response is lost, choose **Check original image operation**; do not upload it again while the outcome is unknown. Missing local files may need to be selected again for a later step. Voice shows its route before preparing the microphone. **Mute microphone** stops outgoing audio, **Mute speech** silences playback, and **End voice** closes the connection. These controls do not stop a simulation. ## Find context and review an answer Find saved discussions by their first question and recent preview. In the Workbench browser, use **Show earlier messages** for older turns and **Use current work** to change context. A pending answer keeps its original target. Evidence links open the supporting records. An explanation interprets results; it is not a new measurement. Review proposed changes before **Apply to draft**, **Save** or **Start**, which remain separate actions. In the Workbench browser, **This answered my question**, **Wrong context** and **Incorrect explanation** save local feedback. **Draft a correction** adds editable text without sending it. **Save answer as a local note** keeps a copy in that browser. These notes and reviews stay until you clear the site’s local data; they do not upload feedback or request replies. Native notes use your library settings. ## Recover the original answer Return to **Ask Roboty** to recover an answer if you left the discussion. **Stop answer** requests cancellation; check for the Mac’s confirmation. It is separate from simulation and hardware Stop. An uncertain answer stays available and is not requested again automatically. ## An uncertain answer If the Mac confirms an unknown outcome, choose **Keep unresolved** to stop checking. The original request and unknown usage stay saved. This does not retry the request or confirm cancellation. To ask again, start a **New discussion**, choose the connection and review reply access. The previous discussion remains available. Content ID: assistant Compiled digest: 7dc97846b4c75d41f7ef6e7c07fc9e70963692cebf8a03c64954e46f3ede5d20 Language: en --- # Keep your Mac available Understand background availability, sleep and recovery. Canonical: https://roboty.dev/guide/troubleshooting/mac-availability Content revision: 23 Platforms: iphone, mac, browser ## When to use it Check availability when Roboty cannot reach the selected Mac, or before leaving the Mac to use your phone elsewhere. ## Steps 1. Keep the Mac awake and logged in. For phone connections, open Roboty on the Mac, choose **Settings → iPhone Connection**, then choose **Enable availability**. Using only the Mac's open local workspace does not require background availability. 2. If macOS asks for approval, open Login Items settings, approve Roboty and return to the companion. 3. Closing the window or quitting the app keeps enabled background hosting available while the Mac stays awake and logged in. **Stop background hosting and quit…** is the separate menu action that stops it. After sleep or restart, wake and log in before expecting the phone to reconnect. 4. Read the companion’s status if it needs attention. Resume restores paused availability. Try again retries a reported startup failure. ## What to expect The phone can reconnect to the same Mac without opening its window again. Availability means the service is reachable. The selected simulation still needs its own readiness checks. Resuming availability never starts another experiment. On Mac, closing the window and Quit wait for new workspace edits, recording location, goal Undo and unfinished discussion to be retained locally. This does not save a new experiment revision. If storage cannot retain new edits, Roboty keeps your work open. Already saved local work does not need another write. Unfinished project details have their own **Save**, **Discard changes** and **Cancel** review before replacing that project, closing the window or quitting. Workspace, Settings and Help keep those fields available. Discard removes unsent edits. It does not cancel a Save already sent to this Mac. Stop remains available for an original operation during the review. If you choose Stop, Roboty records that request locally before closing. Stopping is not yet confirmed. Reconnect to inspect the original operation. ## If something goes wrong - Wake and log in to a sleeping or restarted Mac. Check Roboty’s background approval and whether availability is paused or disabled. - Pausing or turning off availability can interrupt active work. To stop hosting and quit, read the confirmation, then choose **Stop and Quit** or **Cancel**. Reconcile the original operation on the phone before starting another. Saved experiments, results and pairing stay available. Interrupted work does not resume automatically. - If repeated recovery has stopped, read the confirmed failure in the Mac’s details before Try again. On the phone, drafts and downloaded results remain usable while the Mac is unavailable. - If Quit reports a save failure, read the named record and storage reason. Recover workspace storage, then choose **Retry saving locally** or try Quit again. Unreadable original records stay intact. ## Screen lock and display off You can keep automatic display-off and screen locking enabled. Supported application actions use the running workspace and do not need to click its window. The Mac must remain awake and logged in. Display-off and sleep are different states. A stopped service or protected-storage prompt still needs its normal recovery action. UI automation and screenshots retain their own visible desktop requirements. On iPhone, system actions require local authentication and foreground Roboty. They do not provide the Mac's background availability. A device-local draft and a Mac workspace remain separate until an explicit transfer. ## Opening a workspace on this Mac Choose Open workspace to connect the Mac app to its local records. If startup fails, Roboty shows a confirmed reason when available. Saved work and the original operation remain retained. Choose Open workspace to retry that same workspace. A retry does not start another experiment. If another local service occupies Roboty’s connection address, review that service before deliberately closing it and retrying. Roboty does not close it for you or switch to different records. An unknown failure or a connection that is still starting is reported separately. Background availability has its own recovery control: use Try again for its reported failure, or Resume when availability is paused. Opening the local workspace does not enable background availability. ## Assistant connection and usage [Continue in Ask Roboty](/guide/use/ask-roboty#assistant-connection-and-usage). ## Assistant on Mac [Continue in Ask Roboty](/guide/use/ask-roboty#assistant-on-mac). ## ChatGPT account on Mac [Continue in Ask Roboty](/guide/use/ask-roboty#chatgpt-account-on-mac). ## Reply access and usage [Continue in Ask Roboty](/guide/use/ask-roboty#reply-access-and-usage). ## Keep the whole question [Continue in Ask Roboty](/guide/use/ask-roboty#keep-the-whole-question). ## Questions in the Workbench browser [Continue in Ask Roboty](/guide/use/ask-roboty#questions-in-the-workbench-browser). ## Find context and review an answer [Continue in Ask Roboty](/guide/use/ask-roboty#find-context-and-review-an-answer). ## Recover the original answer [Continue in Ask Roboty](/guide/use/ask-roboty#recover-the-original-answer). ## An uncertain answer [Continue in Ask Roboty](/guide/use/ask-roboty#an-uncertain-answer). Content ID: availability Compiled digest: 421c922dc2ca80762975cc79a8672963a4cf278cb03e9113838f9c961e2b3b40 Language: en --- # Prepare a private experiment brief Review selected evidence and optional notes before export. Canonical: https://roboty.dev/guide/use/private-briefs Content revision: 3 Platforms: iphone, mac, browser ## When to use it Prepare a brief when you want a private file describing retained results for explaining an outcome, comparing a change or investigating a failure. On the connected native workflow, open **Review and handoff → Prepare experiment brief**. The resulting private briefing file helps a person or agent read selected evidence and your optional notes. It is different from a portable experiment file, which carries supported setup/evidence for a compatible recipient to inspect and copy into local work. [Saving and transfer](/guide/use/browser-experiments) compares the choices. ## Steps 1. Choose Prepare experiment brief in Review and handoff. Select 1–20 retained results and the investigation question. 2. Leave Include my selected results’ questions and notes off unless you want that text copied to the Mac. If enabled, inspect the exact selected interpretation. Unsent draft notes are excluded. 3. Connect to the selected Mac and choose Prepare private preview on Mac. Read the complete preview for private information and correctness. 4. Acknowledge that you reviewed the contents and have permission to export them, then choose Export reviewed brief and a local file destination. ## What to expect The exported private file contains reviewed retained evidence and only the phone text you selected. Preparing or exporting a brief does not start an agent, simulation or automatic provider upload. ## If something goes wrong - Offline, you can read this guide and select cached results, but preparing or approving the brief needs its Mac. - If evidence or the preview changed, prepare and review it again. Change selection returns to the choices without exporting. - If you do not want to disclose the contents, leave approval unchecked and return to your experiment. Exporting a local file and sharing it with someone are separate choices. Content ID: briefs Compiled digest: 773832b75802660cd1ca0ed0bf307ddd981625ce14246f344c147a69ad687a24 Language: en --- # Change one thing and compare Ask a useful question without losing your first attempt. Canonical: https://roboty.dev/guide/use/change-one-thing Content revision: 7 Platforms: iphone, mac, browser, agent ## Name your question Start with one concrete question: will changing the target height make this goal reachable? Record your expectation before the second attempt. ## Keep the baseline Retain the first executed revision and result. Return with Edit goal. Change one supported value so that you can explain what is different. The new draft does not change the old result. ## Review another attempt Prepare and explicitly confirm the new attempt through the selected owner. Compare like tasks and methods. If the method, starting conditions or success criteria also changed, name those differences rather than attributing the result to height alone. ## Interpret carefully Useful evidence includes failure. A better result suggests a next question, not universal superiority. Training, automatic improvement and physical generalization require their own workflows and evidence. ## Lesson 3: a fair comparison ### Example Return to the same table-mounted arm. Trial A uses our target (20, 0, 15) cm and the 1 cm success rule. A **controller** is the program that chooses how the arm moves. The following fictional results are supplied for this exercise. You do not need to run a simulation. | Trial | Target height | Controller | Final distance from target | | --- | --- | --- | --- | | A | 15 cm | Original program | 2 cm | | B | 17 cm | Different program | 0.5 cm | In both trials, X = 20 cm and Y = 0 cm, the arm starts in the same position, and the success rule stays within 1 cm. ### Your turn Write or choose your answers before checking: 1. Which trials meet the success rule: A, B, both or neither? 2. Name the two things that changed from A to B. 3. Can these results show that raising the target caused the improvement? 4. You want to investigate height alone. Choose a fair comparison with A: **C:** height 17 cm, original program, same starting position and success rule. Or **D:** height 17 cm, different program, same starting position and success rule. 5. Before looking at the explanation, predict whether C will succeed, fail, or remain uncertain. What measurement would you need to check your prediction? ### Check your reasoning 1. **B only.** Its 0.5 cm error is within 1 cm. A’s 2 cm error is outside it. 2. **Target height and controller.** Both changed, so the improvement could relate to either change or their combination. 3. **No.** These two trials do not isolate the effect of height. 4. **C.** Compare A and C with only target height changed. Keep the controller, X and Y, starting position and success rule fixed. 5. **Any of those predictions is a starting hypothesis, not an established result.** C has not been run and no result is supplied. Measure its final distance from its target, then compare that distance with the 1 cm rule. Record both your prediction and the outcome, even if they disagree. You have designed a comparison that isolates one change. Repeated trials would still be needed to assess consistency. Fictional examples and simulated results do not establish how a physical robot will perform. Ready to apply the three lessons? [Choose your next step](/guide/get-started). ## From this written example to a live task The fictional 1 cm final-position rule above is a teaching example. A live task has its own displayed success criterion. Roboty’s supported Reach criterion requires the tool point within 12 mm for 250 continuous simulated milliseconds. Read the rule shown with the selected task before comparing an actual result. Content ID: compare-one-change Compiled digest: 7679d151b41236402446a8c037755e8b6c07be166b2add83293e3c702d4f3a39 Language: en --- # Connect a computer Add a Mac, choose it and keep its workspace separate. Canonical: https://roboty.dev/guide/setup/connect-a-computer Content revision: 13 Platforms: iphone, mac, browser ## When to use it Add a computer when you want it to run simulations and keep saved experiments and results. Choose a laptop that travels with you or a desktop Mac that stays at home. Connect supports Macs running the Roboty companion. You can edit a local draft before adding one. ## Steps 1. On the intended Mac, open Roboty → **Settings** → **iPhone Connection**. If availability is off, choose **Enable availability** and complete any macOS approval. Then choose **Pair iPhone** for a fresh code. This is separate from opening the Mac's own local workspace, which does not require background availability. 2. On your phone, open Connect → Add computer. Scan the code or paste its invitation, then choose Pair or Trust and pair invitation. Scanning asks for Camera permission. Pasting does not need the camera. 3. Open the computer’s settings in Connect to give it a recognizable name. Repeat for each Mac. 4. Choose a saved computer explicitly in Connect to return to its workspace without pairing again. Finish or reconcile a pending operation before switching. ## What to expect The selected Mac and connection status appear in Connect. Each computer owns its experiments and history. The phone keeps separate drafts, notes and downloaded results for each. Local and Tailscale routes to the same Mac use the same workspace. Adding another computer does not enable sync. Optional [iCloud sync](/guide/use/icloud-sync) replicates supported saved content separately. Local preparation and uncertain operations remain with their original computer. The Mac app must be open for its cloud changes to transfer. For a Mac on another Apple Account, export the selected work from its source device, move the file using your chosen method, then use **Import file…** on the receiving Mac. Review each supported item before copying it. This makes independent local copies with source references. It does not link the two libraries or copy connection and readiness settings. ## If something goes wrong If no Mac is paired, Connect helps you add one. You can keep editing locally. If a saved Mac is offline, keep it awake with Roboty available and reconnect to that same Mac. If access needs renewal or its identity needs verification, follow the specific message in Connect. Keep the original draft and any pending attempt. - Code expired? Open Roboty → Settings → iPhone Connection → Pair iPhone on your Mac to get a new one. - Can’t connect? Keep your Mac awake and open Roboty on it. If you need to pair again, get a new invitation from that Mac. - Can’t switch computers? Check or stop the current attempt first. ## Pairing and access details A code expires after two minutes. If you cannot scan it, paste the invitation instead. If access was removed or Roboty no longer recognizes the Mac, pair again using a new invitation. Check the Mac’s name before approving it. Restarting your Mac or changing its network address should not require pairing again. Remove computer removes this phone’s access to the Mac. Your saved work stays on the phone. To also remove the phone’s access on the Mac, revoke it there. ## Keep the original attempt available The workspace selector names the selected Mac. Opening Connect or Connection details does not stop an attempt. Its status and available Stop control remain accessible while you inspect the connection. If the connection is lost, preserve the original operation and check it again on the same Mac. An unknown state is not a confirmed stop. ## USB installation and debugging USB lets Xcode install and debug Roboty. Roboty’s connection to the Mac still uses the network. A cable alone does not provide it. Updating the apps should preserve pairing and private records. Phone and Mac versions must be compatible. ## Pair without using the camera On your Mac, open **Settings → iPhone Connection → Pair iPhone**. Choose **Copy private invitation**, then paste it into Connect on your iPhone. Share it only with the phone you intend to pair. The invitation expires after two minutes. Use **Get new code** when it expires, then copy the new invitation. ## Review paired phones On the Mac, **Settings → iPhone Connection** lists paired devices and their access. Choose **Revoke access** beside the intended phone and review the device name and short device ID before confirming. If that phone pairs again while the review is open, refresh the list and review its current access. Revoking access prevents that pairing from connecting. It does not delete saved records or confirm that a physical robot has stopped. Use the original operation's Stop and recovery controls for that work. A phone can pair again only with a new private invitation. Content ID: computers Compiled digest: a24894d02d6b326c880b5c6a1cb61c597e085d203863554a89b5661f62628b2f Language: en --- # Review simulation recordings Review saved simulation recordings and choose the data you need. Canonical: https://roboty.dev/guide/use/demonstrations Content revision: 6 Platforms: iphone, mac, browser ## When to use it Use Review demonstrations when it is exposed or the Mac has retained captures. This is review of existing simulation evidence, not permission to begin capture, physical teaching or training. ## Physical recordings are a separate path This screen reviews **simulation recordings** and their retained numerical evidence. It does not list, review or export recordings from a physical arm. Use [physical setup and control](/guide/setup/physical-robot) for the hardware procedure, and read [tools and data formats](/guide/setup/robotics-tools-and-data) for supported export formats and current physical recording limits. Reading either guide does not start capture or grant permission to move an arm. ## Steps 1. Connect to the owning Mac and open Review demonstrations. Choose a retained capture and inspect its recorded samples, missing channels and outcome. 2. Add a label or retain annotation if useful, then choose Save review on Mac. These annotations are separate from the original outcome. 3. If dataset selection is exposed, select an inclusive sample range and its training, validation or test split. Add it to the selection. 4. Back in Demonstrations, review the complete selection and recorded cadence. Acknowledge data permission and choose Save selection on Mac. ## What to expect The Mac retains your review or exact private dataset selection for its existing exporter. Selection does not convert data, upload it or train a model. Historical review can remain available after new dataset selection is disabled. ## If something goes wrong - This guide works offline, but demonstration evidence is fetched from its Mac. Reconnect to inspect or save a review. - Missing observations or actions remain missing. Do not label a phone trace as useful training data merely because it can be inspected. - If captures changed, required channels are missing or splits are incompatible, read the Mac’s blocker and revise the selection. Cadence must match actual observations. Saving does not invent or resample missing data. ## Reuse outside Roboty A saved selection, a standard dataset and a shared experiment package are different things. Read [robotics tools and your data](/guide/setup/robotics-tools-and-data#what-can-travel-between-tools) for supported LeRobot formats, additional Roboty evidence and current physical recording limits. File compatibility does not establish training value, grant source rights or validate another arm. Content ID: demonstrations Compiled digest: 838dd6c303504095235348af441e9a3b74bf680169fb3db6da699690133f4949 Language: en --- # 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 --- # Do I need a robot, an iPhone or a Mac? Learn what each device contributes before setting anything up. Canonical: https://roboty.dev/guide/setup/devices Content revision: 16 Platforms: iphone, mac, browser, agent ## Start on your phone An installed Roboty app opens without website login. You can learn, edit a camera-free goal, keep local drafts and review retained local results without a Mac connection. A physical robot is unnecessary for these steps. ## When a Mac helps A connected Mac owns its own workspace and supported simulations. Keep it awake, logged in and reachable while using that route. The phone is the interface. The selected Mac performs the attempt and retains its records. USB is useful for development installation and observation. It is not a substitute for Roboty's authenticated runtime connection. Nearby connections use a reachable local network. Remote access needs the configured private network route. ## Can the phone run a simulation alone? Support depends on your app, device and selected task. Use this device appears only when the app can offer local simulation. If it is unavailable, you can keep editing locally or select a connected Mac. ## Can I use only a Mac? Yes: the Mac workspace has its own controls and records. Pairing a phone is optional for that route. Use the available supported task and readiness shown by the Mac. ## Requirements and where work is saved | Route | What you need | Where the work lives | | --- | --- | --- | | Installed Mac workspace | A matching invited Roboty for Mac build and a task that reports ready | Records stay in that Mac installation. Optional iCloud sync can replicate saved content. Pairing is separate. | | iPhone or iPad local workspace | A matching invited app build | Local drafts and downloaded results stay on that device. Local simulation is offered only for a supported device/profile. | | Connected Mac workspace on a phone | Compatible apps, trusted pairing and a reachable awake Mac | The Mac runs the attempt and keeps original results. The phone retains its separate draft/context and selected downloaded records. | There is no universal OS-version promise for every task. Follow the requirements supplied with your invited build and its actual readiness check. [Find your version](/guide/setup/install#find-your-installed-version) before reporting a mismatch. ## What changes with a physical robot? Hardware adds mounting, power, calibration, supervision and installation-specific stopping requirements. A successful simulation does not prove that physical motion is supported. Begin with [Add a supported robot](/guide/get-started/physical/equipment) for your exact kit. The Mac owns USB and the managed hardware component. A paired iPhone is optional guidance. Saving preparation is available independently of qualified hardware operation. Follow the specific blocker shown beside a procedure. Roboty for Mac manages its own runtime. Roboty operation requires no separate Python or conda installation or AI provider setup. Suppliers own assembly and firmware servicing. Roboty guides supported necessary motor configuration and calibration using its managed component. Installed users choose **Add a robot**, and new users [apply for invitation-only beta access](/download). A follower can complete setup without a leader. The separate leader-following test remains unavailable until both arms and its operating prerequisites are present. Under Explore more, for how Roboty uses LeRobot and MuJoCo, alternative upstream interfaces and what can travel between them, read [robotics tools and your data](/guide/setup/robotics-tools-and-data). The web can explain physical preparation but does not operate USB hardware. ## Robot setup from iPhone Open Home → Add a robot. With no selected Mac, choose Connect a Mac or Get Roboty for Mac for invitation-only access. With a saved offline Mac, reconnect to that computer. When connected, review preparation for the named Mac. Read setup guide and Prepare offline remain useful without a connection. Local drafts stay in their original workspace. Pairing does not move an unpaired draft or enable sync. Optional [iCloud sync](/guide/use/icloud-sync) follows saved personal content, while preparation and operation recovery keep their original Mac. A pending preparation save or hardware action keeps its original Mac. Use Review robot preparation / Stop to inspect it. Protected local operator recovery must be performed on that Mac. 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. ## Keep track of your Library On iPhone, Library names its selected location. If a selected Mac disconnects, its Library stays selected and shows **Offline**. Reconnect to that Mac to read or change its contents. Choose **Use this device’s Library** to switch deliberately to the phone's reusable content. A connection loss does not move or delete saved work. Original pending requests remain attached to their Mac. ## Continue a phone goal on your Mac In the phone's local goal editor, open **More → Continue this goal on \[Mac name\]**. Connect a Mac first if none is selected. Choose **Save on iPhone and review** for unsaved changes, or **Review copy** for a saved goal. Review the named Mac and selected goal, then choose **Copy goal to \[Mac name\]**. The copy becomes an independent project on that Mac. Open the copied project when ready. Your original goal, notes and recorded attempts stay on the phone. This copy includes no personal notes, recordings or active operation. A source guide reference stays with a goal that came from a learning guide. Review it under Included source guide reference. The Mac checks compatibility during preparation. **Prepare** and **Start** remain separate actions. If delivery is uncertain, reconnect to the original Mac and choose **Retry original request**. Roboty reconciles that same copy. **Work on → Mac** still opens the Mac workspace without copying the phone's goal. Content ID: devices Compiled digest: 7639b473b61759cc9569cc2a9c66e26e3d80d131ba1611c4e0f8c64a15ac48c6 Language: en --- # Projects and experiments Open projects, edit goals and reuse saved starting points. Canonical: https://roboty.dev/guide/use/experiments Content revision: 39 Platforms: iphone, mac, browser ## Choose a storage location Choose **This device** or your selected Mac before creating work. A project groups related experiments in that location. **Templates** keeps reusable starting inputs. **Library** holds saved reusable ingredients. Connecting to a Mac does not transfer a project. ## Choose a goal Choose a task you want the robot to attempt. Review the project and starting inputs before creating it. Follow the instructions for your device below. ## Edit and save Edit a project's name, description and tags in **Project details**. Limits and field messages explain invalid input. Save retains the submitted details. Newer typing stays unsaved until its own Save finishes. On iPhone, leaving unsaved project details offers **Save**, **Discard changes** and **Keep Editing**. A failed or uncertain Save keeps its original request and fields available. Do not repeat an uncertain operation as a new request. ## Add related work and continue Open a project to continue its named experiment or choose a specific row. Draft, saved goal and recorded result describe different states. Returning from an editor keeps the originating project and browsing context. An empty active project offers a new experiment. Restore an archived project before adding work. A combined source points to its named destination. **Duplicate experiment** creates one independent experiment without adding a template. Choose **Move to project** or **Combine into another project** to search and review a named destination. Recent choices help with repeated organization. The named recent organization action remains available after navigation or reopening. Undo refuses later conflicting changes. Only the most recent 100 local organization recovery handles are retained, with invalidated handles retired first. Saved experiments and results remain intact. ## Review imports and selected sharing Import review names its destination. Choose a new project, an existing project or Templates where offered without selecting the file again. Changing the destination requires a fresh review before creating a copy. Recognized browser experiment files open the supported experiment review with their project context retained. Unsupported items remain in the original file. Open **Share selected contents** when needed. Select the saved experiments, leave recorded results off unless wanted, and review the named versions and exclusions. Raw JSON is available under **Exact included file**. Changing a selection invalidates its review. **Download reviewed file** is separate from review and does not send or publish it. Private notes and device credentials are excluded from this project export. ## Projects and Templates Projects group experiments and their saved versions. Open a project to continue, or use Search, Pin and Archive to organize your library. Archive preserves its experiments and results. All experiments also includes unfinished drafts and imported work. Compact rows show the name, experiment count or task, and abbreviated date. Dates from earlier years retain the year. On Mac, hover over the date for the full value. Select a saved experiment to inspect it, then choose Open experiment or press Return. On Mac, Roboty uses one main workspace window. Settings and Help keep your current project, search and unfinished fields available. Project details require **Save**. Before replacing a project or closing with unsent changes, choose **Save**, **Discard changes** or **Cancel**. Discard does not undo a Save already sent. If its result is unknown, inspect or retry that original request before choosing another mutation. Templates reuse saved inputs to create independent experiments. Their source results remain with the originals. Using a template does not start a simulation. Each device or selected Mac keeps its own library. Connecting does not transfer work. Linking robot preparation to a project does not establish readiness to move a robot. ## Organize projects Move keeps an experiment's saved versions and results together. Combine moves the source project's experiments into the selected project and archives the emptied source. Review the named projects and affected experiments before applying either action. Cancel keeps the current organization. Undo works while no later change conflicts. ## Make a variation Choose Duplicate experiment or Duplicate project to start independent work from saved inputs. The source stays available. Results from the source remain reference evidence. They do not become successful attempts in your copy. Use with another setup opens a compatibility review. Read what carries over, what changes and what is missing or unsupported. A physical intention retains the goal in words. It does not copy simulation coordinates, calibration or permission to move a robot. Complete the selected setup through Robots before considering physical work. ## Reusable setup Open **Library** to keep reusable robot configurations, tasks, methods and scenes. **Robots** opens your physical robots directly. On Mac, Roboty opens its local storage when needed. This does not start a simulation or connect a robot. A workspace is the computer or device that owns those records. It is not a robot profile or an online account. On Mac, Library initially shows all saved work. Use **Show** to filter robot configurations, tasks, methods, scenes or experiments. **New → New robot configuration** creates a reusable description. In **Robots**, select your robot in the list or choose **Add a robot** to prepare another. Its page shows the current setup step, connection status and next action. A project is optional for setup and practice. Opening a saved experiment's reusable setup keeps that experiment selected, including when it uses another category. A failed read shows its reason and **Retry reading** rather than an empty library. Choose Add, then Experiment to combine saved ingredients. Choose later leaves a slot unfinished. Save the draft without installing a runtime. Edit an ingredient to create a new version. Existing experiments keep their selected version until you adopt a newer one. Duplicate configuration creates independent local work. Select an experiment to review Use with my setup. Unknown facts need confirmation. Unsupported means this build has no matching execution integration. Open experiment appears for a supported simulation selection. Preparation and Start still check current availability and permission separately. In a saved experiment, choose More, then Reuse saved setup to open its exact ingredients. In an empty Library, open **Reuse existing experiments**, then choose **Add existing experiments** to copy saved inputs into Library. Use **Import → Import file…** for a selected reusable file. **Import → From existing experiments…** is also available when Library already contains work. Original records stay unchanged. Choose Intended use when saving an experiment. Physical preparation keeps the goal and ingredients as a recipe. Its checklist separates the actual unit, your environment observations and missing registration or method qualification. Open physical preparation to use the existing setup guide. A recipe does not convert simulation coordinates into robot commands. Copied or changed setups need fresh confirmation of inherited observations. In the ingredient editor, open Confirm setup facts after checking the actual setup. Your confirmation is recorded separately from Roboty's automatic checks. A task describes the goal and success check. A method describes how to attempt it. A scene describes relevant surroundings and conditions. Changing the robot or scene may leave earlier data useful for inspection while making direct comparison, training or control unsuitable. ## Keep reusable starts Save a valid saved version as a personal template. Save new version keeps the earlier template inputs available. Existing projects keep the version they used. Preview a selected version before using it. A project template creates related experiments together. Getting started groups templates and guides without running them in sequence. ## This device Open All experiments to search saved experiments, unfinished drafts, recorded attempts and imported source work in this device's library. The search scope is shown above the results. If simulation preparation is unavailable, a valid changed goal can still be retained with Save revision. Saving a goal does not qualify it for simulation or start an attempt. ## iPhone and iPad Choose New project, select a starting goal and choose Use template. Cancel creates nothing. New project creates separate work even when another project is open. In a project, New experiment adds the chosen goal to that project. Add from Template Library reuses a personal or imported template there. Choose Continue for the named retained experiment, or Open beside another experiment. Empty and archived projects offer the applicable creation or restoration action. Project details contains its name, description and tags. The actions button beside each experiment contains Move and Duplicate. Template previews keep the primary action visible. More details contains the source, version and exact inputs. ## Home on Mac **Recent projects** lists projects by their latest change or saved experiment. Choose **Grid** or **List**; Roboty remembers the layout. Each project shows its experiment count and last change. **Resume experiment** returns to your current draft, saved goal or result. Work without a saved experiment is labeled **Unsaved draft**. If projects cannot load, choose **Retry** or **All projects**. Previously loaded projects can remain visible for the same workspace. Switching workspaces clears the list until the selected workspace loads. If asked to **Open workspace**, do so before browsing its library. ## On Mac Choose **Home → Try a simulation** for a Reach draft, or **Projects → New project** to choose a task. In a project, **New experiment** adds work there. Follow [Open and edit on Mac](#open-and-edit-on-mac) to save, preview and run it. Use [Templates on Mac](#templates-on-mac) for saved starting points. If the workspace is closed, choose Open workspace before viewing projects. A failed library read shows its reason and a retry action. An empty library is shown only after a successful read. Projects shows descriptions, experiment counts and edited dates when available. Select a row to keep your place, then press Return or choose Open. You can also double-click a project. In a project, choose Open beside the experiment you want. Its task and saved date help distinguish experiments with the same name. Project details contains its name, description and tags. Experiment actions contains Move and Duplicate. The project’s More menu contains pin, archive, duplication and combination controls. Library actions in the toolbar contains Import project and All experiments. To reuse saved ingredients in the current goal, choose More → Reuse saved setup. Library opens with the saved source selected. Return to experiment brings you back to your unfinished goal. Editing reusable definitions or reviewing variations stays in the main window. Save applies the reviewed change, and Cancel returns without applying it. Help opens in the main content area. Choose a topic under More details for extra instructions. Back to your task returns to the editor, including after reading a related topic. The sidebar and any active Stop action remain available. Open All experiments to search saved experiments, unfinished drafts and received experiments by title. Search, filters and your selected record remain when you inspect a result and return. An unchanged retained draft does not need another copy. If retained drafts fill the available space, inspect a draft you no longer need and choose Move to Trash. Confirm the named retained copy or choose Cancel. This leaves your current draft, saved experiments and results intact. Restore the retained copy with Put Back in Finder’s Trash, then reopen the workspace. In this guide, a draft is editable work, a saved revision is one retained version of its goal, and an attempt is one execution of a frozen revision. Editing a later draft leaves an earlier attempt unchanged. [The storage reference](/guide/setup/devices#requirements-and-where-work-is-saved) identifies the device that keeps each copy. ## Templates on Mac 1. Choose **New project** or a project’s **New experiment**, then **Use saved setup**. 2. Choose **Preview** beside a starter or saved template. Review its inputs, then **Use template** or **Add experiment**. This does not start a simulation. 3. To save your own template, open a saved experiment and choose **More → Save as template**. Review its source and saved version, then **Save template**. Unsaved edits, personal notes and recorded results are excluded. Cancel creates nothing. 4. Use **Manage templates** in Library actions or More to inspect saved starts and review new versions. ## Open and edit on Mac 1. Open a project, then choose **Open** beside an experiment. 2. Edit the goal in the diagram and Goal inspector. Click the experiment name in the header to rename it. Robot and simulation context remain visible. Position fields use centimetres. Your draft is retained locally on this Mac. Use the fixed toolbar Save action to confirm a saved version. Its status explains unchanged, pending or blocked work. 3. Choose **Preview goal** to check the setup. This does not start a simulation. 4. Choose **Start simulation** when ready. Confirm one attempt at the saved version. 5. Inspect recorded attempts in **History**. Choose **Edit goal** to return to editing. ## Choose where work stays The steps below are for **iPhone connected to a Mac**. Phone-local work stays separate. Changing storage location does not move a draft. ## When to use it Use a draft to change a goal. Use a saved experiment to continue an ongoing question or compare attempts. A run is one attempt at a frozen revision. ## Steps 1. Choose New experiment, or choose a saved experiment to continue it. Give the experiment a recognizable name and edit its supported goal. 2. Your editable work is saved locally. Drafts on this device lets you restore earlier local drafts when you switch experiments or create a new one. 3. When ready and connected, choose **Prepare simulation** on iPhone. Then Start simulation asks for explicit confirmation of one attempt at the saved revision. Editing a draft cannot change an attempt already running. 4. Open Experiments and attempts for Recent runs or History. Use Edit goal to return from a workspace result to editing. ## What to expect Draft edits remain on this phone in the selected computer’s workspace. Saved revisions and runs remain on their owning Mac. Reopening a result shows its executed revision, rather than silently substituting the latest draft. ## If something goes wrong - Offline, continue editing or reopen a retained local draft. Reconnect to the same Mac for saved records that are not cached and for new attempts. - If a save or Start response is lost, reconnect and check the original operation. Do not start replacement work while its outcome is uncertain. - If a new goal was created on the selected Mac but your current draft could not be saved, keep the editor open and resolve the save problem. Choose Retry opening selected saved goal to reopen that same goal without creating another copy. - If another client changed the experiment, follow the conflict message and review the newer revision. If saved workspace recovery is required, original data is preserved and writes pause. Use Retry saved workspace after resolving the reported problem. Content ID: experiments Compiled digest: 516510bd5d2b27a66582d4f508712cf01eaa773613dab4f1dc9f37ef0266debd Language: en --- # Connect your own agent Use supported application actions with explicit ownership and access. Canonical: https://roboty.dev/guide/use/your-agent Content revision: 10 Platforms: iphone, mac, browser, agent ## When to use it This is an advanced developer integration through the current local application interface. Its bounded example ends with a prepared experiment and performs zero simulations. Reading public Help, connecting an operating client and using an embedded assistant are separate activities. Use a matching Roboty development app on the owning Mac, or the source development setup below, with owner-reviewed application access. The installed helper does not require a repository or separate Python installation. Public app acquisition remains invitation-only. To have an agent explain the guides without operating Roboty, use [Help for your agent](/guide/agents) instead. ## Steps Read Help, prepare the owning host, review enrollment/delegation, discover permitted tools, then author/read/prepare a task. Execution requires separate actual admission. Use the sections below in that order. ## What to expect The client uses the same revisions, operation receipts and evidence as the app. Your agent must support this application interface. Documentation MCP alone cannot operate Roboty. ## Guided setup in Workbench Open **Connect an agent** in the protected Workbench discussion. Choose the recipient, the installed helper and private workspace paths, then select read access or access to save and prepare a Reach experiment. Review the time, call and sharing limits before **Prepare setup instructions**. This example permits zero simulations and no provider requests. The browser prepares instructions locally. It does not enroll a client, create a credential, check connection status or grant access. The human owner reviews and runs the exact enrollment and delegation requests on the owning Mac. Keep request files private and retain their original UUIDs. Never paste a credential token into the guide or another product without reviewing its recipient and scope. After successful owner commands, enter the returned client and grant UUIDs to prepare configuration for a compatible stdio MCP client. The client must support launching the installed helper with those arguments. The example does not grant access to existing experiments automatically. The owner selects any additional record scope separately. Use the prepared owner status request to check the current client state. After a lost response, inspect the original request UUID instead of repeating setup with a new identity. Use the current client revision from the owner list for the prepared revocation request. Revocation blocks new access but cannot recall records already received. End presence when leaving. The raw CLI steps below remain available. ## If something goes wrong Inspect the original request after uncertain delivery. The trusted owner can inspect, Stop or revoke independently. Never copy cookies or provider credentials. ## Read Help with an agent [Agent documentation access](/guide/agents) provides [the index](/guide/llms.txt), [complete Markdown](/guide/llms-full.txt) and the development-only read-only documentation MCP. Hosted documentation MCP is not currently available. Reading these instructions does not connect to your host or enroll a client. If you only want help reading the guides, you are finished with setup: give your agent the index or the selected article's Markdown. The remaining steps connect an operating agent and require an owning Mac workspace and the human owner's access review. Choose that path only when you intend to operate the local application interface. ## Use the installed Mac interface Open the intended workspace in the matching Mac app. Its bundled helper exposes `Roboty.app/Contents/MacOS/RobotyAgent cli` and `RobotyAgent mcp`. Use your actual app path and the same private workspace root throughout. Omitting `--port` discovers and checks that running owner. A stopped workspace must be opened through its normal owner. The helper never starts another copy. For example, a local owner can discover supported actions with: ```sh /Applications/Roboty.app/Contents/MacOS/RobotyAgent cli discover --owner ``` Use `--root /absolute/private/workspace` when the running workspace uses a custom location. Local owner access and a delegated agent credential are separate routes. Review enrollment and delegation below before connecting an external client. An agent's own operating-system access is outside the tool's restricted credential boundary. The host can serve application actions with its display off or screen locked while it remains awake, logged in and able to read its protected storage. Sleep, logout and secure-storage prompts can still require the person. This does not change the Mac's power or lock settings. UI clicks and screenshots have their own desktop requirements. See [Mac availability](/guide/troubleshooting/mac-availability). ## Use iPhone system actions In Shortcuts, use **Run Roboty action** with an application request. This advanced route requires local authentication and foreground Roboty. It uses the same live device workspace as the app. It does not run an always-available phone server. Start with a real lowercase UUID and this request shape: ```json {"schema_version":1,"request_id":"YOUR_CANONICAL_UUID","action":"discover","arguments":{}} ``` Follow returned pages and schemas. Read the current draft revision before an update or save. Keep each write's original UUID. A newer human edit makes an old revision invalid. Device-local records stay on that device unless explicitly transferred. Paired host actions use the selected Mac's separate records and current availability. Neither route supplies physical permission. ## Workbench web and MCP The protected local Workbench web uses the same host application operations. Browser-only unfinished text stays with its browser owner until saved. Public website Help and documentation MCP remain read-only guidance. The installed `RobotyAgent mcp` helper accepts `--credential` and an optional `--grant`. With an exact finite grant it exposes typed `roboty.` tools for that delegation. The source equivalent is `workbench:mcp`, prefixed with `bash scripts/with-runtime corepack pnpm`. The normal transport is stdio. Loopback HTTP MCP uses authenticated HTTPS and requires its explicit enable option. This is not a public hosted MCP endpoint. No adapter grants extra tools or renews an allowance. ## Trust the owning workspace CLI and stdio MCP authenticate the owning workspace through its private HTTPS identity before sending an agent credential. Keep `--root` set to the intended workspace. An explicit `--port` does not bypass that identity check. Existing client IDs, grants and operation records remain intact. For optional HTTP MCP, use `https://127.0.0.1:8767/mcp` with the listener port you selected. Configure the client to trust only the owning workspace's `external-tls/server.pem` certificate for this connection. Keep that file private and obtain it from the owning workspace, never from a network certificate prompt. Do not disable certificate verification or install it in the system trust store. The client must support an explicit CA file or equivalent connection-specific trust setting. A client without that setting cannot use this HTTP MCP route. For the supported Python SDK, construct a client-specific verified context: ```python import ssl import httpx2 context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) context.minimum_version = ssl.TLSVersion.TLSv1_2 context.load_verify_locations(cafile=workspace_certificate_path) http = httpx2.AsyncClient(verify=context, trust_env=False, headers=reviewed_headers) ``` Supply that client to the SDK's `streamable_http_client`. `reviewed_headers` contains the authorized credential's authorization header. Load it from its protected file and never print it. Use the canonical HTTPS loopback URL above. A normal host restart preserves the certificate. A changed, expired or incomplete identity stops the connection. Preserve the workspace and inspect the original operation before retrying. Have the workspace owner reconcile the certificate and the client's trust configuration. A failed connection never authorizes re-enrollment, replacement of saved identities or a new operation. ## A supported headless workflow For the source development route, prepare the owning Mac with [development prerequisites](/guide/setup/developer). Use your intended retained private workspace root consistently. The example root below is isolated, not another installation's records. The foreground headless owner uses the same application as the graphical app without an embedded assistant or provider. ```sh bash scripts/with-runtime uv sync --locked --project apps/workbench bash scripts/with-runtime corepack pnpm workbench:headless --root "$HOME/Library/Application Support/Roboty Agent Workspace" --port 8765 ``` Stop the foreground host normally when finished. Do not install a startup service. Optional product MCP transports require the explicitly installed optional SDK and their own authenticated loopback/stdio setup. The basic CLI does not. ## Operate Roboty separately The human owner reviews these private files before submitting them. The examples are inert schemas, not permission for a live enrollment or trial. ### Enrollment Save `/private/tmp/enroll.json` with: ```json { "action": "enroll", "arguments": { "name": "local developer client", "credential_file": "/private/tmp/roboty-client.json", "read_only": false } } ``` Submit it through `bash scripts/with-runtime corepack pnpm workbench:agent owner --root "$HOME/Library/Application Support/Roboty Agent Workspace" --request /private/tmp/enroll.json --request-id UUID`. Use a newly chosen UUID for this operation and retain it with the exact file. The owner creates the protected credential file once, returns `client_id`, and never prints the token. Enrollment grants no execution permission. ### Review the recipient before permitting transmission The example below permits selected experiment reads and sets transmission to true. Review which client receives those records and whether it forwards them to a model provider or hosting service. A local client can still disclose data outside your Mac. Review that provider's policies and configuration before permitting this route. Removing access later cannot recall information already received. [Privacy](https://roboty.dev/privacy#your-own-operating-agent) explains this separate route. Keep the host workspace in the private retained location shown above. The request and credential paths under `/private/tmp` are disposable example locations. Put real credentials and any request/operation records you need to retain in an owner-only private location outside Git. Keep exact original request identities for recovery. ### Finite delegation Use the returned client UUID in `/private/tmp/delegate.json`: ```json { "action": "delegate", "arguments": { "client_id": "RETURNED_CLIENT_UUID", "policy": { "capabilities": [ "tasks.discover", "experiments.save", "experiments.read", "experiments.prepare" ], "resources": [], "tasks": ["so101-reach"], "duration_seconds": 900, "transmission": true, "limits": { "tool_calls": 12, "transmission_bytes": 1048576, "simulation_runs": 0 } } } } ``` Review scope and explicit disclosure consent, then submit the file using the same owner command with its own retained request UUID. This narrower example allows authoring/preparation, not simulation start. Retain the returned grant UUID. Expiry, revocation and current presence still apply. Private credentials/request files stay outside Git and public Help requests. ## Discover and prepare a task The client saves `/private/tmp/discover.json` with the returned grant: ```json { "grant_id": "RETURNED_GRANT_UUID" } ``` Run `bash scripts/with-runtime corepack pnpm workbench:agent discover --root "$HOME/Library/Application Support/Roboty Agent Workspace" --credential /private/tmp/roboty-client.json --request /private/tmp/discover.json`. Discovery returns permitted tools and their actual argument and result schemas. Follow `next_cursor` under the same grant until it is empty. A changed selection requires fresh discovery. Use the same `--root` on every command and preserve returned opaque handles. Before writes, declare logical presence with `workbench:agent presence`, the protected credential and a request file containing `{"active":true}`. Heartbeat every 30 seconds while active and send `{"active":false}` on departure. Presence is not a grant. Use `experiments.save` to author the supported nonpreset Reach goal, retain its returned opaque revision handle, then `experiments.read` and `experiments.prepare`. Submit tool requests through `workbench:agent execute`, prefixed with `bash scripts/with-runtime corepack pnpm`, with `--credential`, `--request` and explicit `--request-id UUID`. Requests contain `grant_id`, `tool`, `arguments` and, where discovered, `expected_revision`. Preserve returned handles. Another client's raw IDs are invalid. Named calls can use `call TOOL --grant GRANT_UUID --arguments JSON` with the same credential and root. Supply `--expected-revision` where required. Retain the write UUID before sending it. Preparation never runs physics. The example delegation excludes `simulation.start`. An actual attempt needs separately reviewed delegation, readiness and finite admission. Product transports never expose arbitrary shell, filesystem, SQL, provider proxy or physical movement tools. ## Recognize completion and leave 1. After discovery, use the returned schema for `experiments.save`. Check the response for the saved revision handle and retain it. 2. Read that handle with `experiments.read`. Confirm the same authored goal and revision before preparing it. 3. Use `experiments.prepare` only with those discovered arguments and the same revision. A prepared response is the endpoint of this example. A rejected response supplies the reason to resolve without starting another operation. 4. Send presence with `{"active":false}` when leaving. This ends presence, not the original request or its records. Stop the foreground host normally when no original work remains active. No `simulation.start` capability is present in this delegation. Do not add it just to complete this example. ## Recover the original operation Keep the exact request UUID and arguments. Lost responses are unknown: inspect the original identity rather than starting replacement work. `workbench:agent inspect`/`cancel` requests contain the returned `grant_id` and `operation_id`. Use permitted evidence reads for original results. Cancellation is a request until cessation is confirmed. An accepted response is not task completion. CLI failures and unknown effects return a nonzero exit code. MCP reports them as tool errors with the original identity. Read measured task outcome separately from transport delivery. Large selected results use private digest-checked artifact pages, not public file links. Expiry/revocation blocks new effects. The trusted owner can independently inspect or stop the original operation using its client/operation IDs without renewing a revoked grant. Stop the explicitly started host normally. Compatibility with every conversational agent is not guaranteed. Content ID: externalAgent Compiled digest: c8482176546ad665ab62e35b045c044ecb076457b9bf2dd7080f6f517a953de8 Language: en --- # Understand your first result Tell the requested goal, preview and measured attempt apart. Canonical: https://roboty.dev/guide/use/first-result Content revision: 10 Platforms: iphone, mac, browser, agent ## The goal A goal describes what you wanted. The chosen task defines what motions and success criteria are supported. A picture of the target is an intention, not measured robot state. ## The preview Preparation checks a candidate and may estimate feasibility. It helps you decide whether to try. It is not evidence that an attempt succeeded. ## The attempt An attempt uses a frozen revision. Read its outcome, method, target and limits. Keep failures and cancellations: they explain what happened, even when a later attempt succeeds. ## Recorded playback Playback shows retained samples from that attempt. It is read-only. Missing samples or unavailable downloads are gaps, not permission to invent a smooth trajectory. Replay does not start another attempt. ## Learn from one difference Write what you expected, what you observed and what you would change. One success does not prove reliability across every target, another installation or a physical robot. A programmed controller's success also does not mean the robot learned a new policy. ## A target and a measured attempt ![Illustration, not run evidence: a tool point is asked to move from the origin toward a target. The intended line does not show the actual executed trajectory.](/guide/assets/reach-goal.svg?digest=f71df5e87142ce2232ceeac7a18e230bf9ad5cd3de3e484b5949662ec0bfec1d) The target `X = 0.20 m` describes an intended coordinate in the declared robot frame. It is not a guarantee of reachability. Read the supported bounds in your workspace before choosing a value. | What you see | What it means | | --- | --- | | Target marker | Requested tool point. Intention | | Preparation preview | Candidate feasibility. No completed attempt | | Retained samples | Recorded evidence from the original attempt | ### On iPhone Use Edit goal to return to the selected workspace. Precise coordinates offers accessible metric values. Place in AR is optional. ### On Mac The result above the scene describes the whole attempt. The blue marker is the robot’s tool tip. The green marker is its target. A new recording opens paused at its first state. Choose **Play** to watch the retained states. **Slow (0.25×)** takes four times as long as the original simulation. Choose **Very slow (0.1×)** to inspect motion at one tenth speed. Use **Previous recorded state**, **Next recorded state** or the slider to inspect one pose at a time. The displayed time is simulation time. The distance describes the selected state, even when the attempt’s final result says Succeeded. Poses change only at recorded times. Motion between retained states is not shown or invented. **Replay** returns to the beginning without starting another simulation. Reopening a result restores your selected state. Open **Result details** for the success rule, final measurements and limits. Missing scenes or samples remain explicit gaps. Return to my draft restores your separate current goal. Edit this attempt’s goal opens the recorded revision for correction while preserving the original result. You do not need to pair a phone just to interpret the Mac result. Choose **Explain this result** to ask about the selected attempt beside the scene. Review the named context before allowing replies. **Open discussed result** returns to the exact attempt without closing assistance. For general frames and transformations, see [Modern Robotics: rigid-body motions](https://modernrobotics.northwestern.edu/chapters/chapter3/). ## Lesson 2: intention and evidence ### Example Use the same table-mounted arm and target: (20, 0, 15) cm from the base. Success means the tip ends within 1 cm of the target. These are fictional teaching cards, not actual run evidence. - **Card A · Request:** “Move the tip to (20, 0, 15) cm.” - **Card B · Preview:** “The target appears reachable.” A preview is a prediction before movement. - **Card C · Measured result:** “After the attempt, the tip ended 2 cm from the target.” A measurement records what happened. ### Your turn Choose your answers before checking: 1. Which card tells you what actually happened: A, B or C? 2. Did the attempt meet the 1 cm success rule? 3. Suppose you have only A and B because no attempt was made. Which conclusion is justified: **“It succeeded”** or **“It may be reachable, but it has not been tried”**? 4. Suppose an attempt finished, but its final measurement is missing. Can you decide whether it met our success rule? ### Check your reasoning 1. **C.** A describes the intention, B predicts feasibility, C supplies a measured outcome. A prediction can be wrong. 2. **No.** The measured 2 cm error exceeds our 1 cm tolerance, even though the preview looked promising. A finished attempt can still miss its target. 3. **“It may be reachable, but it has not been tried.”** A preview cannot establish successful movement. 4. **No, the result is unknown from the supplied information.** “Finished” tells us the attempt ended. Without its final measurement, we cannot check the distance. Missing evidence does not prove success or failure. You can now separate what was requested, what was predicted and what was measured. Next, use measured results to plan a fair comparison. ## From this written example to a live task The fictional 1 cm final-position rule above is a teaching example. A live task has its own displayed success criterion. Roboty’s supported Reach criterion requires the tool point within 12 mm for 250 continuous simulated milliseconds. Read the rule shown with the selected task before comparing an actual result. Content ID: first-result Compiled digest: 45d6d057df9a4a60d1884c992d84a58ef8dc3394ff592981875be4d391a9e8e9 Language: en --- # Add a supported SO-101 Save your robot, configure only what it needs and preserve calibration through one Mac workflow. Canonical: https://roboty.dev/guide/setup/physical-robot Content revision: 50 Platforms: iphone, mac, browser, agent ## Choose the experience Open **Robots** in a matching Roboty for Mac development build. With no saved robots, choose **Add a robot**. The short guide asks for your kit and assembly state, then shows a review and the appropriate next step. A name is optional. Choose **Add robot** to save, or **Save for later** when identification or compatibility review is still needed. An unverified state is not a factory-default state. The Add a robot workflow is in development and access is invitation-only. Powered owner commissioning and ordinary operation remain separately qualified. A public native installer is not available. The initial route supports the reviewed Seeed SO-ARM101 Standard or Pro follower profile on a compatible Apple Silicon Mac. Confirm the actual variant, servo labels, supply and controller. Unknown, custom or modified hardware needs compatibility review. Your iPhone can accompany the Mac through the existing paired connection. It is optional and does not configure the controller by USB. A leader, camera, microphone, model, cloud account or Project is not required to add the follower. Simulation remains available without hardware. A present adult operator must review the supported mounting, correct power supply, arm support and accessible disconnect before any powered step. Read the stopping procedure before connecting power. Saving a draft or reading this guide does not authorize hardware access. ## Your robots With one saved robot, **Robots** opens that robot directly. **Add another robot** remains available. With multiple robots, select one in the Mac list or use the **Robot** picker in a compact view. Each page keeps its exact installation identity, name, saved details, original operations and next available action. A rename does not replace calibration. **Add a robot** starts a new draft. **Cancel new robot** returns to the previous robot. If you entered details, choose **Keep draft** or **Discard draft**. Kept drafts remain on the originating device until saved to the selected Mac. Reconcile a pending operation before leaving it. **Last viewed** records instruction-reading position. It does not record motor configuration or verified calibration. A completed guide never grants operating permission. **Library** contains reusable configurations, tasks, methods and scenes. A Project is optional. ## Parts and workspace Your supplier owns mechanical assembly, wiring diagrams, firmware servicing and repairs. Roboty owns supported software configuration and calibration. Some kits assign motor IDs before assembly. Follow the supplier's sequence for your exact kit, then return to Roboty for the software step you need. Review [Seeed's SO-ARM101 instructions](https://wiki.seeedstudio.com/lerobot_so100m_new/) for the exact Standard or Pro kit, motor configuration section and assembly order. The [upstream SO-101 guide](https://huggingface.co/docs/lerobot/so101) is another software/assembly reference. These resources were reviewed October 23, 2026. They do not establish compatibility for a different supply, board or modification. The written guide remains useful when a video is unavailable. An assembled arm may need access to motor cables. Use the matching supplier connector guidance and minimize dismantling. If the intended connector or electrical isolation is uncertain, pause and ask the supplier. Do not guess from a motor response or cable color. ### Prepare the stopping procedure before power A present adult operator must support the arm, secure its mounting, clear its workspace and keep the physical power-disconnect method accessible. Confirm the actual motor labels and power supply before following a powered step. A generic motor model response cannot establish the correct voltage. Before changing cables, request Stop, wait for original device work to cease and follow the supported resting and power-disconnect procedure. Account for USB and external power as required by the actual board. Confirm the applicable sources are disconnected before rewiring. A software Stop button is not a physical emergency stop. Torque release can let the arm fall under its own weight or load. ## Founder assembly resources ### A note from Gabe I’m assembling my own SO-101, and this is the video I’m using. I’m sharing it here in case it helps. I may add more resources as I go. [Watch the assembly video](https://www.youtube.com/watch?v=mFnJjWp-K-A) Follow your kit provider’s instructions for your exact hardware. This personal reference is not a Roboty assembly procedure. The note is available offline. The video needs internet access. [View assembly resources](/guide/setup/assembly-resources). More resources coming soon. ## Save what you know The guide retains answers locally as you move between **Kit**, **Assembly** and **Review your robot**. Back preserves your answers. The final **Add robot**, **Save for later** or **Save robot details** action saves to the selected Mac without opening hardware and returns to the robot’s page. Its primary action opens the relevant next task. Use **Help identify my kit** to compare your order, packaging and actual labels with the supplier reference. Unknown, custom or modified hardware cannot use the ordinary connection route. An unknown assembly state also needs identification before guided hardware setup. You can save either for later without claiming readiness. Motor settings are considered during controller preparation for unfinished kits. An assembled arm with unknown settings starts with the admitted connection check. Uncertainty alone never means settings should be overwritten. Calibration choices appear at the calibration step. User declarations and actual device observations stay separate. **Kit details changed** and **Controller settings changed** have separate save controls. Save the relevant details or controller profile explicitly. Use Reload only when you intend to replace the local draft with its saved version. A failed read preserves unsaved work. On iPhone, **Continue offline** retains local input and instructions. Saving to the named Mac remains separate. Pending saves retain their original identity. **Check original save**, **Retry original preparation save** and **Cancel pending preparation save** recover that metadata operation. They do not repeat hardware actions. Existing unfinished and older prepared-only records remain readable with their original calibration and uncertainty. ## Before final assembly If your supplier calls for motor initialization before assembly, use only the supported isolated-motor step, then return to its assembly instructions. Calibration and ordinary operation require complete assembly and their own prerequisites. If the arm is already assembled, use the supported connector-access route instead of starting assembly over. ## Choose your USB controller Connect the intended USB controller to your Mac with a data-capable cable. Choose it in **Choose your USB controller** and save the controller profile. This only selects the board. It does not open the motor connection or move the arm. Roboty manages its setup software, so you do not need a separate Python, conda or LeRobot installation. If no controller appears, check the data cable and USB connection, then choose **Refresh devices and status**. If two boards look identical, connect and identify the intended board using its supplier instructions. Do not infer a leader or follower from port order. For an unfinished kit, describe whether the supplier already configured the motors and follow its order for necessary motor setup and assembly. For an assembled arm with unknown settings, start with **Check all six joints** after reviewing the required hardware and power checks. If configuration is explicitly needed, review **Set up motor IDs**. A failed connection check alone does not establish that motor settings need changing. Preserve correct settings. ## Set up one motor at a time A motor ID is the address Roboty uses to tell one joint from another. New motor configuration is currently follower-only. Use this route only when configuration is needed and the matching procedure is available. Select the physical joint. With original device work stopped and applicable power disconnected, electrically isolate that single motor using the supplier's connector instructions. Here, electrically isolate means only that selected motor is connected to the controller, using the supplier’s wiring diagram. Confirm the actual isolation. One address replying cannot prove that duplicate-address motors are absent. Restore power only when the selected procedure permits it. Review the selected controller and motor. **Identify isolated shoulder pan motor** (or the selected joint) performs bounded discovery. Review its observed initial address and baud rate, then use **Configure shoulder pan motor as ID 1** (or the selected joint and ID) for that named joint. This is a consequential action that can disable torque, unlock configuration and change the motor ID and baud rate. It does not enable ordinary movement. The profile owns the mapping: shoulder pan 1, shoulder lift 2, elbow flex 3, wrist flex 4, wrist roll 5 and gripper 6. Readback, not the number of completed screens, records progress. If an action is interrupted or its acknowledgement is missing, retain the original operation. Use the offered bounded observation/reconciliation path. Do not repeat the write, configure all six again or try a full-chain broadcast. **Motor checklist** shows recorded results for this robot. **Choose next unchecked motor** changes only the selected joint. It never starts configuration. Results become recorded after the original session is closed and reviewed on the Mac. After all six results are recorded, **These motors are configured. Continue** saves your updated declaration. It does not replace the full-arm check. Stop device work and confirm the supported power-off disposition before each cable change. An expected wiring disconnect pauses the procedure. Reconnecting never automatically resumes it. After all necessary motors are configured, restore the full chain with power off, then verify communication and the relationship between physical joints and addresses through the approved supervised procedure. Six identical model responses do not establish that mapping. No automatic sweep is used. ## Assemble your arm Continue mechanical assembly with your supplier. Preserve its motor-before-assembly sequence if applicable. An already-assembled arm does not repeat this stage. When assembly is complete, choose **I’ve finished assembly. Update my robot**. Review support and power labels again, then continue to the full-arm check. Confirm completed assembly and support before calibration. The optional [founder note](#founder-assembly-resources) and [assembly resources](/guide/setup/assembly-resources) supplement the supplier's written instructions. ## Connection, calibration and control Roboty checks its managed component before a physical session. You do not need to install Python, conda, LeRobot or LeLab separately. A missing or incompatible component needs a matching Roboty for Mac build from the installation maintainer. Select the intended controller and review available device details. Passive discovery does not open the bus. Port names, discovery order and a remembered path do not identify the arm reliably. Identical boards or missing serial numbers may need explicit review. Leader and follower controllers must be distinct when both are used. Save the controller profile, then use the Mac's local session review for the exact next procedure. The review can temporarily pause Roboty's host and request local authentication. It records finite permission, not hardware success. A paired phone cannot confirm that someone is beside the robot. **Connection check** is a separately admitted observation. It does not initialize motors, rewrite calibration or enable motion. Preserve valid settings. Reconnection, changed hardware and expired permission require fresh checks without automatically repeating a write. **Check all six joints** is the full-arm connection check. Before calibration, confirm the physical joint/address mapping in this connection session. Support the arm in the instructed posture. All six torque readings must already be off. Roboty refuses this observation if torque is enabled or unknown and does not silently disable it. Select one joint, take the before reading, manually move only that physical joint as instructed, then take the after reading. Review every channel and explicitly confirm the observed relationship. Repeat for all six joints. These raw readings and your confirmation are evidence, not an automatic movement sweep or an invented movement threshold. Close the successful original connection after its work ceases. Calibration admission requires that retained connection and all six operator-confirmed observations, not a saved checkbox. Confirm mapping inside the connection session. You do not need to predeclare it in the robot’s kit details. ## Preserve or create calibration New calibration creation and application are currently follower-only. Existing leader calibration import, readback and qualified leader-following remain available. Choose the route that matches this arm. **Import original calibration…** reads inert local data. **Check existing calibration** reads the device for comparison. **Apply selected calibration** writes reviewed values. **Save new calibration** completes the admitted creation procedure. None of these actions means the same thing, and import never silently applies a file. The calibration step starts with **Check existing calibration**. If you already have a file, import it, save the controller profile and verify it before considering any write. If you are unsure, use **Help find my calibration file** or ask whoever configured this arm. Roboty does not automatically search local folders. When no usable original file is available, deliberately choose **Create or apply calibration**. Uncertainty does not select new calibration for you. No write happens until you explicitly confirm it. The supported file handoff is LeRobot 0.6.1 SO-101 calibration JSON for the exact arm and role. The upstream default directories are `~/.cache/huggingface/lerobot/calibration/robots/so_follower/` and `~/.cache/huggingface/lerobot/calibration/teleoperators/so_leader/`. A custom directory overrides them. Preserve the original file and select its exact revision before saving the controller profile. Each file must match the selected six joint names, IDs and integer `drive_mode`, `homing_offset`, `range_min` and `range_max` fields. A file from another arm or unsupported exporter is not interchangeable. Import alone cannot establish its relationship to the actual hardware. A mismatch remains blocked until the supported review or explicit write procedure is admitted. Opening the calibration connection is read-only. New calibration requires complete assembly, verified full-chain mapping and the profile's supported resting and manual-position instructions. First support the arm and explicitly choose **Prepare manual calibration**. This disables torque, unlocks configuration and sets the operating mode. Wait for all torque readings to confirm disabled before manually positioning each joint roughly in the middle of its permitted travel. Midpoint refers to each joint’s travel, not the arm’s height above the desk. The [official SO-101 calibration video](https://huggingface.co/docs/lerobot/en/so101#calibrate) illustrates the midpoint and range process. Use Roboty’s session controls for the current procedure, and the matching supplier instructions for your exact kit. **Set calibration midpoint** checks torque again before writing homing values. Then use **Record joint ranges**. The visible joint list shows where travel samples are still missing. Use **Save new calibration** after reviewing every permitted joint’s travel. Raw counts are sensor readings, not degrees or operating limits. **Apply selected calibration** is a separate explicit alternative before manual preparation or before setting the midpoint. Move only as instructed, without forcing stops. Wrist roll uses the pinned full-turn range and is not measured like the other bounded joints. Missing, discontinuous or implausible observations need review rather than invented limits. Roboty preserves original calibration and records device writes separately from saving a successor file. If saving fails after a write, keep the original result and follow reconciliation. Do not assume nothing changed or repeat calibration to repair a missing file. After the original session is closed through protected cessation and power review, **Recover calibration file** can republish its retained planned JSON without hardware effects. This is an unverified candidate. Select it and perform separate readback before treating it as verified. Joint calibration does not establish workspace/camera registration or safe Cartesian motion. On the robot page, open **Maintenance → I moved or changed something** routes mounting, cables/controllers, joints/motors and unexpected behavior to the relevant review. Preserve still-valid calibration. Replacement invalidates only the affected readiness while retaining history. ## Supervised control and Stop Adding a follower finishes on the same named robot. **Continue later** retains progress. **Test & practice** remains the existing leader-following workflow and needs both prepared arms, verified calibration, matched poses, operating limits and separate qualification and permission. Adding a follower does not require that test or automatically start movement. After practice, the owning Mac can [review the retained recording and create a selected local dataset](/guide/setup/robotics-tools-and-data#what-can-travel-between-tools) when the original session is closed and a supported converter is available. Reading or exporting retained data does not start another capture. **Stop robot** remains available for the original operation while reading Help, waiting, navigating and recovering errors. Cancellation requested, worker ceased and actual hardware disposition are different facts. A late response cannot turn an uncertain result into permission to continue. No new owner may bypass an unresolved original session. Use **Close original connection** and protected original-Mac recovery for the retained session. Support the arm and follow the provider's power-disconnect procedure. Unknown effects remain unknown. Roboty never reconnects, resumes or repeats an uncertain hardware action automatically. A stopped session or sample count does not prove physical success. ## Save your setup and shut down Save changed details and controller selections explicitly. Review configured, calibration-verified, unknown and operating requirements separately. Request Stop, establish original device-work cessation, support the arm and follow its documented power-disconnect procedure. Close and reconcile the original session as directed. On a later return, reopen the same robot. Roboty rechecks controller and calibration continuity without reinitializing valid motors. A changed controller, motor, calibration or component needs the relevant fresh review. Relaunch restores context and original records, never expired authority. ## Understand your setup results **Your setup results** shows saved robot details, individual motor results, the full-arm joint check and calibration readback separately. A prepared arm can pass the full-arm check without configuring all six motors again. Results come from closed, matching physical sessions on the original Mac. Reading a step, selecting a kit or importing a calibration file does not pass a check. **Follower setup checked** appears only after the full-arm joint mapping and selected calibration have retained matching results, with changes saved and no original session needing attention. **Continue setup** returns to the earliest unfinished step. **Continue later** keeps the same named robot and its records. Optional **Test & practice** does not block follower setup or start automatically. Content ID: hardware Compiled digest: af5527f9879984135b7cb435600817a25078a3139445897523c30671b7c5197d Language: en --- # History and offline results Find attempts and understand which results are downloaded. Canonical: https://roboty.dev/guide/use/history Content revision: 5 Platforms: iphone, mac, browser ## This device Open Experiments to search local saved work and recorded attempts. Compact attempt rows identify the experiment, recorded date, task outcome and execution state. Dates omit the year only for the current year. On Mac, hover over a date for its full value. Select a record to inspect its details. A completed attempt can still fail its task. A missing outcome remains unknown. Imported source evidence stays separate from your own attempts. ## Choose the right workspace The instructions below describe the connected-Mac route. This device keeps its own goals and results. Device-local simulation is offered only when the selected profile is qualified. Switching workspaces does not move a draft. ## When to use it Open History to find earlier attempts, inspect their outcomes or prepare results to read while the Mac is unavailable. ## Steps 1. On iPhone, open History for the selected Mac. Search experiments or runs and filter by outcome or experiment. 2. While connected, search covers retained records on the selected Mac. Use Load more history when more matching records are available. 3. Open a result while connected to retain its recorded review within the phone’s bounded download library. Check the Available offline label before relying on it offline. 4. Inspect recorded playback and What happened. Back returns to the list with its search and filters preserved. ## What to expect Offline search covers only cached metadata on this device. Only downloaded results reopen without the Mac. Playback is recorded evidence, cannot move a robot and does not create another attempt. ## If something goes wrong - If a result is not downloaded, reconnect to its owning Mac and open it. Cached list metadata alone does not mean replay is available. - If no match appears, clear the search and filters. A later-page error can be retried. Missing dates, outcomes or samples remain unknown. - The download library has a storage limit. Very large results may stay only in the current review, and older downloads may be evicted. In Connect, Remove downloads removes cached records for one Mac while preserving drafts, notes, pending requests, pairing and Mac records. ## Browser workbench history If loading History fails, choose Retry history. The same search, filters, page and selected attempts are retained. Retrying the list does not start or replace an attempt. ## Which browser and which records? The connected History instructions describe Roboty for Mac and its local browser workbench used for development or maintenance. The public **Workspace on roboty.dev** has its own **My experiments** library in that browser. Those libraries are not synchronized by pairing. [Devices and workspaces](/guide/setup/devices#requirements-and-where-work-is-saved) explains local, paired and downloaded records. ## Reading outcomes Simulation time and elapsed time are different clocks. Missing playback samples are not filled in as observed motion. Your notes and interpretation do not replace the authoritative outcome. Inspect recorded details for the executed revision and recorded measurements. Content ID: history Compiled digest: 2eede453fbbffafa345c0dbf9301c859c28a9681e3e93ee21aefaf41d98c4868 Language: en --- # Keep your library in iCloud Use saved work on your Apple devices and keep local work when offline. Canonical: https://roboty.dev/guide/use/icloud-sync Content revision: 9 Platforms: iphone, mac ## Turn on iCloud sync If your installed build offers iCloud sync, open Home → Settings → Library & Sync on iPhone or Settings → Library & Sync on Mac. Read what will be included, then choose Turn on. Use the same Apple Account on your devices. You do not need a Roboty account or a paired Mac to read your saved library. Your existing local work is kept. The Turn on confirmation explains that existing iCloud content and work on this device will be combined. Matching names do not replace existing items. ## What follows you Supported saved projects, reusable robots, tasks, methods, scenes, templates, experiments, notes and completed discussions can sync. Saved unresolved work can remain editable even when it cannot run on that device. Completed result summaries keep their original source and outcome. The iPhone Control detail choice also follows your library. Appearance follows each device’s system setting. Guidance, setup choices and permissions remain local. Unsubmitted questions, unfinished input, local robot connections, calibration and permissions stay on their original device. Sync does not move a running attempt or make a robot ready. Use the original Mac connection for live status and Stop. ## Work offline Keep working while offline. Once a save succeeds, the change stays on that device and waits for a connection. Other devices may receive it later. Open Roboty on your Mac to transfer its pending changes. Sync does not run after the Mac app quits. If iCloud storage is full, your durably saved local changes remain available. Follow the specific status in Settings. A local storage error needs attention before the app can confirm a save. ## Review two versions If the same work changes on two devices, both versions are kept. Open Home → Settings → Library & Sync → Review library and versions on iPhone, or Settings → Library & Sync → Review library and versions on Mac. On Mac, saved work and versions opens in the main window. Select a record to inspect its versions. Back returns to Library & Sync. Inspect the retained versions, then choose Use this version for the intended work. Receiving a change does not replace what you are typing. New versions of a reusable setup or template do not silently change existing experiments. ## Recordings and other large files Large recordings and datasets stay at their source until you select them. In Settings, open Library & Sync, then choose Keep a file in iCloud, select one file and review its name and size. Choose Keep in iCloud to upload it. The limit is 64 MB per file. On another device, choose Download for an available file, then Save a copy if needed. A result summary may be present before its recording is available. A source-only recording still needs its original device. Download cannot recover bytes that were never uploaded. Removing a downloaded copy is different from deleting your original work. ## Continue a saved discussion Choose Continue discussion and review the history to include. On Mac, this review stays in the main window and the new discussion opens in Assistant. A new discussion opens on your selected Mac through the normal connection and provider permissions. It does not replay an earlier Send or resume an uncertain request. An existing draft or pending message must be handled first. ## Turn off or change accounts Turning off stops future sync on this device and keeps local work. It does not delete your iCloud copy. Re-enabling reconciles retained changes. If your Apple Account changes, review the recovery choices in Library & Sync on Mac, or choose Review account on iPhone. You can sign back into the original account and try again, keep using the library offline, or use a separate library. On Mac, Saved libraries shows the Current library and any library selected for restart first. Expand Other libraries when shown to browse the rest. Choose Switch beside another library, or Create a separate library, then confirm the named choice. Finish pending changes and turn off background availability first. The selected library opens after you close and reopen Roboty. Until then, Current library still names the running library. The new library starts with sync off. Previous work and queued changes stay in their original library. On iPhone, Manage saved libraries selects a library for the next app launch. If the cloud copy is missing or cannot be opened, keep local work and follow the recovery message. Rebuild from this device creates a new cloud copy only after confirmation. Files that existed only in the previous cloud copy may be unavailable. Forget from synced library removes supported saved content and its managed sync copies after confirmation. Immutable source records and work pinned by experiments or pending operations cannot be forgotten through this control. It does not erase original files outside Roboty or promise immediate deletion from an offline device. ## Sharing is a separate choice Personal iCloud sync does not share work with another person, publish it or send it to a model provider. Use [selected sharing](/guide/use/sharing) to review exactly what a recipient receives. Read [Privacy](/privacy) for storage and removal choices. If the other computer uses a different Apple Account or cannot use iCloud, use a reviewed selected file instead. Import creates independent local copies. It does not merge or automatically keep two libraries in sync. A selected file is not a full backup. Content ID: icloud-sync Compiled digest: 9c95496672038d4be0a9fb21e172ecf2f50fdc39acfea369fb131e41314c7ecd Language: en --- # Compare task improvements Compare results and choose what to try next. Canonical: https://roboty.dev/guide/use/task-improvements Content revision: 4 Platforms: iphone, mac, browser ## When to use it Use Try improvements only when it is exposed for a supported saved single-cube experiment, or to revisit retained comparisons. A guide article cannot enable this capability or grant model calls. ## Steps 1. Open Try improvements for the saved experiment. State the question and select the available method. Native search and agent-assisted comparison have distinct runtime and authorization requirements. 2. Prepare comparison, then review its task, limits and disclosure. Review and start and its confirmation are a separate decision to run the finite comparison. 3. Read comparison status and results. Stop requests cancellation. Check status reconciles the original comparison without starting another one. 4. Explicitly select a simulation configuration if offered, or record Keep current, Reject or Inconclusive. Previous comparisons lets you inspect retained results and Restore prior configuration. ## What to expect Selection creates a simulation revision. It does not qualify a physical controller or establish general model superiority. Reduced retained comparisons remain readable offline, while new preparation, status, selection and restoration need the owning Mac. ## If something goes wrong - If Start or Stop is uncertain, reconnect and use Check status for the same comparison. Stop not confirmed means Roboty has not confirmed that the attempt ended. The Mac may have received the request while work is still stopping. Wait for a confirmed terminal status before preparing replacement work. - If the selected agent runtime is unavailable, read its reason. Reading Help does not install a model, add an allocation or expose the capability. - If publication of a selection conflicts with a newer experiment, review the retained decision and use Preserve current experiment when appropriate. Corrupt recovery records block overwrites and preserve original data. Content ID: improvements Compiled digest: 719eedbda22329da93baa55b7570e1a59068f36b8750b4a1ed7a0a5db3dfc88c Language: en --- # Get Roboty and check your version Choose your app setup or explore robotics without an installation. Canonical: https://roboty.dev/guide/setup/install Content revision: 20 Platforms: iphone, mac, browser, agent ## Choose your setup Use Roboty on iPhone to design tasks and review results. Use the Mac app for a connected workspace. [Device and workspace choices](/guide/setup/devices) explains which setup fits your task. Start [learning without installation](/guide/learn), or open your installed Roboty app. ## Private beta access On the Roboty website, choose [Apply for beta](/download) to request iOS, Mac or both. Access is by invitation. Public downloads are not available yet. Selected testers receive installation instructions by email. Applying does not create an account, start a run or guarantee access or a release date. ## Already installed For a supported physical arm, open Roboty for Mac and choose **Home → Add a robot**. Your iPhone is optional. Roboty manages its runtime; no separate Python, conda, LeLab, ChatGPT login or AI provider setup is needed. Supplier assembly and servicing tools remain separate. Use the app’s **Help** for instructions that match your build, including offline. [Choose your device and workspace](/guide/setup/devices), then follow the controls and readiness shown in your app. ## Find your installed version On iPhone or iPad, open **Connect → Connection details**. The report starts with the Roboty version and build number. **Copy report** copies those details for a support request. Review the contents before sending it. On Mac, open Roboty's **Settings → Advanced**, then expand **Diagnostic report** under Connection report. The report starts with the Roboty Mac version. **Copy report** copies the displayed information. This report does not show a build number. Include the version and any build identifier supplied with your installation if support needs it. [Devices and workspaces](/guide/setup/devices) is the shared requirements and storage reference. Use your invited build's requirements and the selected task's readiness message. A newer guide does not make an older build compatible. ## Explore more Repository contributors can follow [development prerequisites and commands](/guide/setup/developer). [Mac setup](/guide/setup/mac) explains host/workspace choices. Development signing and installation are distinct from a public consumer download. ## Prefer to start without an app [Learn robotics](/guide/learn) or [review robot setup](/guide/get-started/physical/equipment) without installing an app. The website explains the physical setup; Roboty for Mac performs component checks and setup procedures. [Apply for beta access](/download) if you need the app. ## Physical setup on Mac If you came to set up a robot, use the invited Roboty for Mac installation. Choose **Home → Add a robot**. The existing Workspace shortcut also opens the same preparation. The Mac manages the hardware connection and saved setup. An iPhone is optional guidance, not the USB owner. The first-use choices also offer **Try a simulation**. Choose what you want to do before choosing an execution device. Returning users resume their retained work. Installing or selecting a journey never enables physical operation. 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: install Compiled digest: d3853b3a7b67de7c11adc3bc2b4df2d7ff1a070b869954aebcee3899ca1ede25 Language: en --- # Learn robotics by doing Work through three guided exercises: define a robot’s task, understand its results and compare one change. No app, account or robot needed. Canonical: https://roboty.dev/guide/learn Content revision: 8 Platforms: iphone, mac, browser, agent ## Start with three short exercises Read an example, work through a thought question and move to the next exercise. You can optionally save your progress in this browser. These exercises introduce task and evidence basics. They do not run a robot or check your answers. [Start the first exercise](/guide/get-started/learning/target) 1. [Define a task and its target](/guide/get-started/learning/target): frame, units and success criteria. 2. [Separate intention, preview and evidence](/guide/get-started/learning/evidence): what each can establish. 3. [Compare one change](/guide/get-started/learning/compare): fair comparisons and limited conclusions. ## Follow your questions For browser experiments, follow the guide for your question: ## Map the twelve investigations Each page names whether you are changing an illustration, reading a recorded example, working through a written case or deliberately running a new simulation. Start with the question you want to answer. You do not need to complete a course or contribute data. Content ID: learn-map Compiled digest: 22f57c161d727c1a34b3ecf1dbf7d1a46c55d88efe22b41a77397a38ad06ac22 Language: en --- # 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 --- # Local networks and Tailscale Reach the same trusted Mac nearby or away. Canonical: https://roboty.dev/guide/setup/networks Content revision: 4 Platforms: iphone, mac, browser ## When to use it Use a local connection nearby. Use your private Tailscale network when your phone is away from the Mac. Both are routes to one computer, not ways to share work between computers. ## Steps 1. Nearby: put the phone and Mac on networks that can reach each other. The Mac may use Ethernet while the phone uses Wi-Fi. Allow Roboty’s Local Network permission on the phone. 2. Away: install and connect your own Tailscale clients on the phone and Mac using the intended private network. 3. On the Mac, open **Settings → iPhone Connection**, pause availability, enable Allow Tailscale connections, then resume. Your Tailscale access rules must allow Roboty’s native port. 4. If pairing remotely, choose Use Tailscale for this pairing code on the Mac and use its fresh invitation. If already paired, reconnect locally once to learn the Mac’s enabled remote route. ## What to expect Connect shows the successful connection method. Roboty reconnects to the selected Mac using trusted local or Tailscale routes. Returning home does not require turning Tailscale off, re-pairing or changing workspaces. Turning off Allow Tailscale connections also clears Use Tailscale for this pairing code. If you enable Tailscale again, choose remote pairing again when you need it. Otherwise, new pairing codes use the local route. ## If something goes wrong - Nearby, check Local Network permission, Wi-Fi, the Mac firewall and guest-network isolation. A guest network may block communication even with internet access. - Away, check Tailscale is connected on both devices, the Mac allows Tailscale connections and its access rules permit Roboty. Tailscale does not wake the Mac or start Roboty. - Read Connection details for the recorded error. An unreachable phone cannot reliably distinguish sleep, firewall, permission or network isolation. Check the Mac rather than assuming a cause. ## Addresses and port The native port is 8766 by default. Current Tailscale support uses private numeric IPv4 or IPv6 addresses. MagicDNS names are not supported. Computer settings can add an address manually after pairing. Every route must verify the same trusted computer. Public forwarding is not needed. ## Developer installation and testing Tailscale connects Roboty to its trusted Mac. Xcode installation and device testing use a separate paired connection. Joining the same tailnet does not establish that development connection. Nearby wireless development depends on Apple's pairing and network requirements. USB remains useful when that connection is unavailable. Content ID: networks Compiled digest: 6a9203f1b5ea1a99ea5f4492b2f00022cb0c5914ca4540f9fa5d96ac6611133c Language: en --- # Questions and learning notes Keep your intention and interpretation with the right attempt. Canonical: https://roboty.dev/guide/use/learning-notes Content revision: 3 Platforms: iphone, mac, browser ## When to use it Use a question or learning note when you want to remember why you made a change and what the result taught you. These fields are optional. They are not an AI chat or a requirement to run a task. In the selected experiment's **Learning note**, a useful question might be: “Will increasing only target height change the final distance?” After the attempt, write what you observed and which measurement is missing. A note such as “the higher goal took longer in these two attempts” is an interpretation of selected evidence, not a replacement for either recorded outcome. ## Steps 1. In Learning note, expand Question for this attempt. Describe what you want to find out, what you expect and what changed. 2. Write what you learned or want to try next. Draft context stays with the draft. The original operation binds its context to its result. 3. When reviewing an attempt, edit your interpretation or add the suggested learning note if useful. Review any context carried from an earlier attempt. 4. Use Keep, reject or inconclusive, and why? and the next-question field to record your decision. ## What to expect Questions and notes remain private on this device in the selected computer’s workspace. Your interpretation stays separate from the Mac’s recorded outcome. Editing notes does not start another attempt. ## If something goes wrong - If you see Earlier unassigned note, inspect it and choose Copy into this note only when it belongs here. Roboty does not silently assign legacy text to a run. - If context was carried from an earlier result, update the question and changed factor for the current attempt. - To include selected results’ notes in a private experiment brief, explicitly opt in and review the exact text. Unsent draft notes are excluded. Content ID: notes Compiled digest: 602240fdc61f9ff570faa4273ac0badf00ab9697a419364cc6657b2d4e876c87 Language: en --- # Place a workspace with the camera Confirm a surface or return to camera-free editing. Canonical: https://roboty.dev/guide/use/place-in-ar Content revision: 2 Platforms: iphone, mac, browser ## When to use it Use Place in AR to relate a virtual workspace to a surface. This is optional for numeric target editing and recorded review. It does not calibrate a physical robot. ## Steps 1. Choose Place in AR and allow Camera access if you want this mode. Move the phone gently while surface coaching finds a stable horizontal plane. 2. Inspect the metric workspace origin and forward-axis preview. Choose Confirm workspace only when the app offers a ready candidate. 3. Edit the target with stable tracking. Adjust height explicitly. Scanning a surface does not set the tool point’s height. 4. Choose Done or Edit target without camera to return to the saved metric draft. ## What to expect Confirmation permits spatial editing for that session. The saved goal keeps its metric coordinates. A surface preview, normal tracking or visible virtual robot does not establish physical alignment or task success. ## If something goes wrong - If Camera permission or tracking is unavailable, use Edit target without camera and the map or precise coordinates. - If tracking is limited, stop spatial edits and follow the displayed coaching. After an interruption, use Restart surface scan and confirm the workspace again. - If no usable surface appears, preserve the draft and use the non-camera editor. Re-registration must not silently change the saved goal. Content ID: placement Compiled digest: 617bf2680d9e127c48444178545549f1aa4ccb1b4034ebdfa97f3cfea0d1b4c2 Language: en --- # Privacy and diagnostics Send feedback, report a bug and manage optional diagnostics. Canonical: https://roboty.dev/guide/reference/privacy Content revision: 13 Platforms: iphone, mac, browser ## Find your question - [Local records and backups](#private-records). - [Optional iCloud library](#optional-icloud-library). - [Messages and diagnostic details](#steps). - [Public sharing and optional contributions](#optional-browser-evidence). - [Operating-agent disclosure](#your-own-operating-agent). - [Terms, ages and physical use](#terms-and-privacy). ## When to use it Read this before using camera modes, preparing a diagnostic report or choosing to share technical errors. Help itself does not record diagnostics, ask for camera access or send reports. ## Steps 1. Camera access is requested by scanning or spatial modes. Camera-free target editing, Help and downloaded result review do not need it. Showing the AR camera does not automatically record or upload its feed. 2. On iPhone or Mac, open Help and choose Send feedback or Report a bug. Write what happened and choose Send. Your email is optional. 3. Bug reports include error details. Use Include error details to change this, or Preview error details to see them. General feedback includes basic app information and leaves recent details off. On Mac, the preview expands inside the message window. Reading it does not change Include error details. Cancel closes the message without sending it. 4. Roboty retries delivery quietly when a connection is available. You do not need to manage saved messages. 5. Extended recording and Sentry remain under Diagnostics. Record for 15 minutes collects more technical events. Share errors with Roboty via Sentry is a separate timed setting. On the website, use [Contact](https://roboty.dev/contact) for feedback or choose Report a bug in the site footer. To correct a guide, choose Suggest a correction beneath the article. Contact keeps the article link in your message and does not include technical diagnostics. The public website and Roboty Guide use Google Analytics cookies to understand visits and navigation. Google Analytics loads automatically after the page loads. Choose Turn off analytics under Website analytics on [Privacy](https://roboty.dev/privacy) to stop future measurement in this browser. You can turn it on again there. This is separate from diagnostics, private experiments and native app activity. ## What to expect A small recent-action summary and the latest structured application failure are kept locally for up to seven days. Sending a message delivers its selected app details to Roboty’s support inbox. Extended local reports stay on the device unless you export or share them. Technical reports exclude camera images, audio, room geometry, drafts and credentials. Error sharing sends new scrubbed technical errors and supported crash/hang details during its consent period. It does not upload previously recorded local history. ## If something goes wrong - A message can be sent even when detailed diagnostics or the selected Mac are unavailable. Extended recording cannot reconstruct activity from before it was enabled. Reproduce a problem only within its normal operating permissions. Do not start a simulation just to read Help. - Sharing expires after 15 minutes. Turning it off cancels pending sends and discards unsent SDK reports. Already sent reports cannot be recalled. - If report preparation fails, check device storage. Delete local diagnostics removes local diagnostic records without changing workspace or pairing. Inspect reports before disclosure, including copied connection details. ## Optional browser evidence [Browser experiments](/guide/learn) work with research and training off. Public sharing is a separate explicit disclosure and never research consent. The optional contribution controls apply only to future eligible synthetic evidence in this browser. Training and longer reviewed dataset retention have separate choices. Enabling them later never upgrades old captures. Ordinary page activity, free text, media and private-world geometry are excluded from the automatic path. Use Stop future uploads, Withdraw prior research permission, Withdraw prior training permission, Delete selected contributed records or Delete all. A management request without acknowledgment remains pending and retries when online. It is not a confirmed server deletion. Keep the private management receipt for recovery. It is a key for managing those contributions, so anyone holding it can exercise its rights. [Browser saving and recovery](/guide/use/browser-experiments) explains how it differs from a shareable experiment file. Local experiments and unrelated public shares remain separate. Live collection is inactive pending the actual operator, jurisdiction, minors, processor and retention review. Read [Privacy](/privacy) and [contribution terms](/contribution-terms). ## Your own operating agent Public Help and Markdown do not expose your experiments. An operating agent is separate: review which records it can read and which client, model provider or host receives them before allowing transmission. A local client may forward received information to its own service. Revoking access blocks future access, not copies it already received. See [Privacy](https://roboty.dev/privacy#your-own-operating-agent) and [Connect your own agent](/guide/use/your-agent). ## Private records Targets, questions, recordings, datasets, calibration and credentials are not consent to publish or upload. Camera recording, dataset capture, export and cloud disclosure retain separate explicit permissions. Removing downloads is different from removing pairing or deleting Mac records. ## Terms and privacy Read [Terms of Use](/terms), [Privacy](/privacy) and [Contribution terms](/contribution-terms). Mac and iPhone Help keep a bundled copy available offline, with its version shown. The current online version may be newer than an installed app's copy. When an effective agreement is presented, choose Agree and use Roboty only after reviewing it. Opening a document or leaving the notice does not agree. Agreement stays local and does not turn on diagnostics, research, training or provider sharing. It never starts a pending operation. Existing records, export, privacy withdrawal, recovery and Stop remain available. Experiment workspaces, installed apps and beta applications are for people in the United States, age 13 or older. Minors need parent or guardian agreement and supervision. Public educational reading remains available for younger learners. Do not submit personal information about a child under 13 through a software or sharing feature. The initial physical-robot path separately requires a present adult operator and excludes children operating the robot. ## Optional iCloud library When available and explicitly enabled, iCloud sync stores supported saved personal content in your private Apple Account. It is off by default and can be enabled in compatible builds. Large private recordings and datasets need separate selection. Credentials, pairing, local calibration and execution permissions stay local. Turning sync off keeps local work and does not delete the cloud copy. An account change pauses sync and keeps the previous library separate. Read [iCloud sync](/guide/use/icloud-sync) before enabling it. This choice does not permit public sharing, research or model disclosure. Content ID: privacy Compiled digest: 7b3305e6be15bd4ed928740859f13c591f34ccdfd10ddbd80e7811295e571f35 Language: en --- # Roboty, LeRobot and your data Understand which tool does what, how to choose a path and what can travel between them. Canonical: https://roboty.dev/guide/setup/robotics-tools-and-data Content revision: 10 Platforms: iphone, mac, browser, agent ## Which tool does what? | Tool | Its role in this experience | | --- | --- | | Roboty | Guides supported robot software setup and experiments, explains choices, retains private records and reconciles the original operation after a failure. Its native Mac interface owns the selected hardware connection. A paired iPhone can provide guidance and supported controls. | | LeRobot | Supplies the initial robot integration and standard dataset tools behind the selected Roboty procedures. It also has its own broader workflows for recording, training and evaluating policies. Reusing its library does not expose every upstream feature in Roboty. | | LeLab | An alternative graphical interface for LeRobot. It has its own setup, recording and learning workflows. Roboty does not embed its complete application or require you to run it alongside Roboty. | | MuJoCo | Supplies numerical physics for Roboty’s supported simulation tasks. Roboty defines the selected task, controller and success rule around that engine. LeRobot also has simulation integrations. Its broader ecosystem is not limited to physical arms. | Use [Add a supported robot](/guide/get-started/physical/equipment) for the Mac journey. Start with the supported robot you have. Preserve supplier assembly order. Roboty guides necessary motor configuration and calibration using its managed component. Roboty manages its runtime internally. Adding or operating a supported robot through Roboty requires no separate Python, conda or LeLab installation, ChatGPT login or AI provider setup. Keep upstream preparation tools separate from Roboty's runtime. Roboty's current native preparation can save facts and profiles. Physical execution requires separately qualified and permitted procedures. A public native installer is not available. A successful simulation does not validate a real installation. ## Choose a platform The iPhone can retain local drafts and supported local results. It uses the selected Mac for physical preparation and controls. The Mac owns USB, the managed hardware component and the private physical records. Pairing, reading Help and saving preparation do not grant permission to move hardware. [Device choices](/guide/setup/devices) explains simulation availability and separate workspaces. [Add a supported robot](/guide/get-started/physical/equipment) starts the physical path. ## Use upstream tools deliberately Read [LeRobot’s SO-101 guide](https://huggingface.co/docs/lerobot/so101) for component setup and calibration, [LeLab’s guide](https://huggingface.co/docs/lerobot/lelab) for that alternative interface, and [LeRobot’s simulation documentation](https://huggingface.co/docs/lerobot/envhub) for upstream simulation options. Roboty’s managed component has its own pinned environment. Upstream installation commands and features may target another version or operating system. Do not install them into Roboty’s component or global Python environment as a repair. A missing component needs the supported Roboty setup path and its displayed readiness check. Before another program opens the controller, stop and reconcile the original Roboty session and verify that ownership has been released. Do not run two device owners at once. When returning, inspect changes to motor settings, controller identity, calibration and limits. A different tool cannot inherit Roboty’s physical permission or installation qualification. ## What can travel between tools? | Material | What reuse means | | --- | --- | | Supported LeRobot dataset | The selected local exporter uses the official writer/reader and declares ordered state/action features, units, action meaning and episode timing. Roboty’s prepared local intake supports bounded numeric LeRobot v3.0 episodes. It is not an arbitrary Hub, video or model importer. | | Extra Roboty evidence | Export metadata can preserve source identity, capture context, original event times and gaps alongside standard dataset fields. Retain the dataset’s description and companion files. Another reader may load standard arrays without understanding those additional meanings. | | Experiment or finding package | A task, reported evidence and explicitly selected interpretation can help someone understand or reproduce an experiment. This is different from a training dataset. The recipient reviews it and creates their own local revision before any separately permitted attempt. | | Original calibration | Roboty preserves the original LeRobot JSON for the selected arm and role. Similar kit names do not make calibration interchangeable between physical arms. | | Permission or validation | These never travel with a file. Another installation needs its own compatible components, calibration, limits, authority and physical checks. | Standard dataset timestamps describe the nominal frame rate. They must not replace the original observation/action event times or erase missing samples. The selected export also distinguishes requested targets from targets actually sent. Neither alone proves measured motion. On the owning Mac, the robot’s **Test & practice** result offers **Review and export recording**. Choose **Read recording** to inspect the original result, saved and pending samples, channel units, setup references and timing. An interrupted recording stays labelled interrupted. Review does not repair it or move the arm. For a closed, reconciled session with a supported converter, enter the task, choose the nominal rate and whether actions mean requested or sent targets, then confirm local export rights. **Create local dataset** uses the existing LeRobot writer and reader. It keeps timing gaps as separate episodes and saves the dataset in this Mac’s Library. **Open dataset folder** opens that local output. Nothing is uploaded or trained. If conversion is unavailable, keep using recording inspection and follow the displayed build/component recovery guidance. If the response is lost, use **Check original export** before another conversion. Original recordings and partial outputs remain retained. Actual installed interaction and useful real-arm exchange still need acceptance. **Review demonstrations** continues to review simulation captures. Compatibility is useful groundwork, not proof that a dataset improves a policy or transfers across robots. Choose a named task and consumer, then check feature order, units, action representation, cameras, timing, calibration differences and source rights. Unsupported or missing channels stay missing. Compare actual outcomes before claiming that extra evidence is more useful. ## Keep control of your data Private setup, calibration and captures remain on their owning Mac. Phone drafts and downloaded reviews have their own local storage. Local storage has limits and is not a backup. Retain a deliberately selected export for important work. Extra evidence does not require automatic cloud collection. Exporting a local file, sending it to someone, publishing to the Hugging Face Hub and contributing to Roboty are separate choices. None happens merely because you connected an arm or read these guides. Inspect the exact files and source permissions before sharing, including any identifying installation metadata. Community datasets also have their own rights and compatibility requirements. Read [LeRobotDataset v3.0](https://huggingface.co/docs/lerobot/lerobot-dataset-v3) for the standard format, [sharing](/guide/use/sharing) for Roboty’s selected package routes and [privacy](/guide/reference/privacy) for separate disclosure choices. 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: robotics-tools Compiled digest: 3f99d40fa6a241afc96a2b0a76fbcf8e55ce4bd2ac536446a2bb302da385b8ae Language: en --- # Share findings, templates and projects Choose exact contents, review the file and share it separately. Canonical: https://roboty.dev/guide/use/sharing Content revision: 12 Platforms: iphone, mac, browser ## Your devices and other people Optional [iCloud sync](/guide/use/icloud-sync) keeps supported personal work on your own Apple devices. It does not share a project with someone else. The file choices below create reviewed recipient copies and keep private content selection separate. ## Selected reusable setup In **Library**, select a configuration or experiment and choose Export. Review the selected contents, then Save file on iPhone or Export file on Mac. An experiment includes its selected ingredients. A single task, method, robot configuration or scene can also be shared. The file excludes notes, recordings, local connections, calibration, permissions and attempt history. Choose Import and review the exact contents before importing. The recipient receives independent local identities and original source lineage. Missing ingredients can be selected later. Imported observations are reports about the source setup, not measurements of the recipient's environment. Unknown robots remain inspectable even when Roboty cannot simulate them. Select an experiment to inspect Reuse and outcomes. Return an observation or correction prepares a selected file for review and saving. Reported success, failure and withdrawal remain attributed claims until independently validated. Copies do not become independent evidence. Sharing the file with someone is a separate action. ## Selected project files Open a project and choose Share. Select the saved experiments to include. Include recorded results is optional and starts off. Choose the exact completed or stopped results to include where offered. Personal notes are excluded. Choose Review contents to inspect the selection, then Export to save it locally. On Mac, Back returns to the selection in the same sheet. Changing the selection requires a new review. Cancel in the system save panel returns to the review with your selection retained. Unfinished operations are not shared as completed results. When working on a selected Mac, Show more experiments loads later entries without closing the sheet. New entries start unselected. You can also share results through their existing experiment or finding controls. A project template excludes recorded results and provides reusable starts. A project file preserves selected relationships and source lineage. Import project file opens a review before creating independent local work or adding selected contents to an active project. Original source evidence stays reported. Import and template use never start a run. Adding another source keeps the earlier original sources available for inspection. Saving to Templates keeps a reusable start in the named local library. It does not publish it. Review the original source, selected version and editable inputs before Use. A local file is not a publication. Send it separately to your intended recipient. Sharing does not grant Roboty research or training permission. On Mac, **Import file…** accepts supported project, reusable setup and experiment files through their existing reviews. A file with several selected items first shows what it contains. Choose a supported item to open its own review. Some items are listed but cannot be copied here, and items with selected dependencies may need Workbench to copy the complete set. Close the review to keep the original file and current work unchanged. Import creates a local copy with its source reference. It does not restore an entire library or move a running attempt. Share from the experiment or finding you want someone to see. You do not need to describe your setup again in the contact form. ## iPhone 1. Open a retained result or investigation and choose Share finding or task template. 2. Choose a finding, task template, or both. Add an interpretation only if you want it included. 3. Choose Prepare privacy review and read every attachment. 4. Confirm that you reviewed the contents and have permission to save them locally. Choose Save reviewed package and a destination in Files. 5. Share that saved file with your intended recipient using your preferred file-sharing method. Preparing and saving the package does not send it to Roboty or publish it. This route uses the connected Mac. If it is unavailable, reconnect before preparing the package. A recipient reviews the imported package before creating their own local revision. Import never starts a run. ## Mac To share a project, open it and choose Share. Select the experiments to include. Show more experiments lets you select later entries without closing the sheet. Additional entries start unselected. Include recorded results is optional and starts off. Review contents shows the selected file before Export saves it locally. Changing the selection requires a new review. Use More, then Save project as template to keep reusable starts without recorded results. Template previews open in the main window. Back returns without creating work. More details contains the source, version and exact inputs. Open the finding or retained result and use its Share finding with a reproducible template or Share and reuse controls. Prepare the selected finding, template, or both. Inspect the complete privacy review and approve the exact package before saving it. Send the saved file separately to your intended recipient. When exporting recorded simulation results, select attempts from one engine version. Export results from different engine versions separately so each file keeps its original conditions. A saved package is a local export. It does not publish the finding or enroll it in research. For a written explanation of selected results, you can also [prepare a private experiment brief](/guide/use/private-briefs). ## Browser In Explore, open Share and choose the scope you need: - A page link shares the investigation you are reading. - A setup link shares supported inputs so someone can make their own local experiment. - Selected file export provides a portable file without uploading it. Review the selection before exporting. - A selected-result snapshot, when the publishing service is available, requires review before publication. It is unlisted, not private: anyone with its link can read and forward it. Hosted result snapshots are currently unavailable. Page links, supported setup links and local file export remain separate options. See [browser saving, sharing and recovery](/guide/use/browser-experiments) for the complete workflow. The project and experiment Import file controls can review a selected file with several items. Open a supported item in its project or experiment review. An unsupported item remains in the file and is not imported by the browser. ## Contributing to Roboty is a separate choice Sharing with another person does not give Roboty permission to collect your experiments or use them for training. Onboarding and interface preferences do not grant that permission either. Optional browser research contribution is off by default and currently inactive. When available, it covers future eligible structured synthetic evidence in that browser, with separate choices for training and longer dataset retention. It does not upload your old library or enroll another device. See [privacy and data choices](/guide/reference/privacy). ## Before you share Read the exact preview and leave out credentials, identifying information, private recordings and material you do not have permission to disclose. A recipient’s successful import does not verify the original result or establish physical robot capability. For an ordinary question, collaboration inquiry, product feedback or article correction, use the website’s Contact page. Sending a message does not publish it or grant research or training permission. Content ID: sharing Compiled digest: 342831b009c9539a652cbf46b8d4d7913d9931fcab575137725c2ba803b061f3 Language: en --- # Roboty software and upstream tools Use the managed component for supported setup. Supplier servicing and optional upstream tools remain separate. Canonical: https://roboty.dev/guide/setup/so101-software Content revision: 6 Platforms: iphone, mac, browser, agent ## Use the managed Roboty workflow A matching Roboty for Mac development build manages its hardware software. Open **Robots → Add a robot** for supported controller selection, necessary motor configuration and calibration. You do not install Python, conda, LeRobot or LeLab to use this route. Access remains invitation-only and powered commissioning is separately qualified. A missing or incompatible component needs a matching Roboty build from the installation maintainer. A separate upstream installation cannot repair the bundled component. Ordinary simulation remains separate from the hardware feature. ## Optional upstream tools The [official SO-101 documentation](https://huggingface.co/docs/lerobot/so101) and [Seeed instructions](https://wiki.seeedstudio.com/lerobot_so100m_new/) own their applicable assembly, firmware servicing and repair procedures. Some kits configure motor IDs during assembly. Preserve that order. These tools may have their own software requirements, but they are not a prerequisite for Roboty's supported Add a robot workflow. An advanced diagnostic needs a concrete purpose and separate device ownership. Stop and reconcile Roboty's original session before another tool acquires the controller. Never use another tool to bypass uncertain effects or unavailable physical permission. ## Calibration exchange Use the exact [calibration handoff](/guide/setup/physical-robot#preserve-or-create-calibration). Import is inert, verification reads hardware, and application or creation needs an explicit admitted write. Preserve original files and record the actual exporter/version. A working upstream robot still needs Roboty-specific verification and permission. ## Assembly resources Follow your exact supplier's written instructions. The optional [note from Gabe](/guide/setup/physical-robot#founder-assembly-resources) preserves his existing personal assembly-video reference. Content ID: so101-software Compiled digest: a407a91aa8127cc19b41376da699f8be4f563ba0b6ff44a1a18ed6eb2eb3e0f0 Language: en --- # Resolve robot setup problems Find the next safe setup or recovery step while preserving original operations and calibration. Canonical: https://roboty.dev/guide/troubleshooting/so101 Content revision: 12 Platforms: iphone, mac, browser, agent ## Start with the exact symptom Keep the original error, operation and calibration files. Roboty handles supported software setup. Suppliers own assembly access, firmware servicing and repairs. Never reset, flash or repeat uncertain writes to make a check pass. | Symptom | Next action | | --- | --- | | Hardware facts or power variant are unknown | Leave the affected procedure blocked. Confirm actual servo, supply and controller labels with the supplier. Do not infer voltage from a generic model reply. | | Assembly is incomplete | Follow the supplier's sequence. Use only a supported isolated-motor initialization step when its instructions call for it. Complete assembly before calibration. | | No USB controller is listed | Check the selected Mac and supplier cable/driver requirements. A listed port alone does not prove communication. | | Identical boards or changed port | Review the intended robot/controller binding. Do not select by discovery order or silently reuse a remembered path. | | Isolated motor is missing or addressing is ambiguous | Stop, follow the safe power-off procedure and inspect the exact isolated wiring. A single replying ID does not prove isolation. | | Motor configuration was interrupted | Keep the original operation and any completed stages. Use bounded read reconciliation of plausible old/new settings. Do not repeat the write. | | Motor mapping or calibration does not match | Review the exact arm, role, mapping and selected artifact. A readback mismatch does not authorize applying or recreating calibration. | | Firmware is incompatible | Use the exact supplier servicing route, then deliberately recheck in Roboty. Roboty does not flash or factory-reset the controller. | | Controller is busy | Preserve its current owner. Close and reconcile the original session before a new one. Do not kill another process to bypass ownership. | | Access or local review is unavailable | Follow the displayed host-specific reason. Protected physical review happens on the owning Mac. A paired phone or saved file cannot grant permission. | | Missing or incompatible Roboty component | Use a matching Roboty for Mac build. Another Python, LeRobot or LeLab installation cannot fill its component slot. | | Disk full or calibration publication failed | Preserve the original receipt. Device writes may have completed even when no successor file was saved. Free only known disposable data and use the deliberate recovery path. | | Check unavailable | Save the relevant facts/profile, inspect the stated mode prerequisite and obtain fresh local review. Full-motion qualification is not an initial motor-setup prerequisite. | | Interrupted or legacy session | Request Stop, inspect/support the arm and retain the original session. Close/reconcile it on the original Mac. Recovery never replays the action. | | Stale controller profile | Reconcile original work before deliberately reloading the saved profile. Preserve original calibration bytes. | ## Setup status could not be updated Retry the original status read and check the selected Mac connection. Offline Help and drafts remain available. A failed read never completes a hardware check. Keep original Stop available and preserve pending identities. ## Return to your stage - [Your robot and requirements](/guide/setup/physical-robot#choose-the-experience). - [Controller selection and connection](/guide/setup/physical-robot#connection-calibration-and-control). - [Isolated-motor setup](/guide/setup/physical-robot#set-up-one-motor-at-a-time). - [Preserve or create calibration](/guide/setup/physical-robot#preserve-or-create-calibration). - [Supervised control and Stop](/guide/setup/physical-robot#supervised-control-and-stop). ## What to include when asking for help Share the exact displayed blocker, app/runtime version, selected robot/role and original operation identity. Exclude pairing credentials and unrelated personal data. Keep device details and calibration private unless you explicitly review a local export. Ask the supplier about uncertain labels, physical access, wiring, power, firmware or repairs. Ask Roboty about its supported procedure, managed component, compatibility, retained results or recovery. An imported file or checklist cannot certify an unseen arm. ## Recover an uncertain original session Request Stop and follow the profile's support and power-disconnect procedure. Keep unknown effects visible. Open the saved robot on the original Mac and choose **Recover the original session on this Mac**. Roboty manages its host pause, verifies original worker cessation and requests fresh local authentication before releasing ownership. Recovery does not reconnect hardware, repeat a write or resume motion. On iPhone, follow the named original Mac and robot in the recovery instructions. A stopped worker and observed power disconnection do not prove whether an earlier uncertain write occurred. Review that outcome through a separately admitted bounded observation. After protected original-session closure and power review, **Recover calibration file** can republish retained planned JSON as an unverified candidate. It performs no hardware action. Select the candidate and separately check existing calibration before treating it as verified. Content ID: so101-troubleshooting Compiled digest: 1f2609175dcf118df8529cde556fffb93e39a3bac5b083d399f24c58ff8f246d Language: en --- # Get started with Roboty Choose a useful starting point, with or without a robot. Canonical: https://roboty.dev/guide/setup/start-here Content revision: 24 Platforms: iphone, mac, browser, agent ### Choose your next step Build your robotics skills and prepare to teach useful tasks. You can start learning without an app, account or robot. ## Choose a starting point - **[Learn the basics](/guide/learn)**: define a task, understand its results and compare one change. - **[Add a robot](/guide/get-started/physical/equipment)**: check the SO-101 requirements and [apply for Roboty for Mac beta access](/download). Already installed? Choose **Home → Add a robot** on Mac. Your iPhone is optional. ## Home in the app On Mac, open a project in **Recent projects**, or choose **Resume experiment** for your current work. On iPhone, use **Continue** or **All projects**. Opening work keeps your draft and does not start an attempt. Use **Projects** for ongoing work, **Robots** for physical robots and **Library** for reusable setups. [Projects and experiments](/guide/use/experiments) explains creating, saving and organizing work. ## Help while you work Choose **Help** for the control or result you are using. On Mac, Help opens in the main content area; **Back to your task** returns to your work. On iPhone, Help opens in a resizable sheet. **More details** shows extra instructions. Stop and recovery remain available during an attempt. App Help works offline and matches your installed build. On iPhone and iPad, **Learn robotics on the web** and **Read full guide on the web** open the in-app browser. On Mac, read the bundled Help or visit Roboty Guide in your browser. For questions about a goal or result, read [Ask Roboty](/guide/use/ask-roboty). ## Keep your place Guides are optional. Use **Back**, **Skip** or **Return to workspace** to leave a tutorial. Reading progress stays on this browser or device; it does not move your experiment. ## Settings on iPhone Open **Home → Settings** for Guidance and controls, Library & Sync, Computers, or Privacy & Diagnostics. In **Guidance and controls**, **Apply** saves your changes; **Cancel** or **Back** discards them. The editor’s More menu opens the same controls. **Show tips again** takes effect immediately. Sync and diagnostics use their own controls. ## Using your own AI agent? [Let your agent read Help](/guide/agents). To connect an agent that operates Roboty, follow the [operating-agent guide](/guide/use/your-agent) and review its access separately. ## Advanced options Repository contributors can [prepare a development installation](/guide/setup/developer). An installed Mac helper also supports agent connections; the operating-agent guide covers both routes. Content ID: start-today Compiled digest: a7d99792e6c93035ae0f283c5dee6fe9eef2a27c228ac0158389f5a1eb22b3c7 Language: en --- # Edit and check a target Edit a target with the map or position fields without a camera. Canonical: https://roboty.dev/guide/use/edit-a-target Content revision: 15 Platforms: iphone, mac, browser, agent ## Choose the right workspace The instructions below describe the connected-Mac route. This device keeps its own goals and results. Device-local simulation is offered only when the selected profile is qualified. Switching workspaces does not move a draft. ## When to use it Change where the simulated tool should reach. The camera-free map and height controls work without a Mac or AR tracking. ## Steps 1. For Reach, click, tap or drag the destination marker. Forward and left are relative to the robot. On iPhone, Height + and − beside the map change height by 2 cm. On Mac, the Goal inspector shows editable Forward (X), Left (Y) and Height (Z) fields in centimetres. Each Mac + or − changes that value by 1 cm. Editing never moves the robot. Undo and Redo sit beside Destination on Mac. On iPhone, use Undo target edit. 2. On Mac, choose the task once in Goal. For a waypoint, choose Waypoint first or Final target above the map. The position fields and map edit that same selection. For a cube task, choose Cube start or Tray destination. Their heights are fixed for the supported scene. If a retained height needs correction, choose Use fixed scene height. Hide inspector gives the diagram more space. Show inspector returns the fields. In a narrow window, scroll below the map to reach them. 3. Direct position fields use centimetres across the native app. X is forward, Y is left and Z is up in the declared robot frame. Negative X is backward and negative Y is right. Saved geometry and exact machine-readable task data remain in metres. Unfinished text stays visible and must be corrected before visual editing or saving. On iPhone, open Precise coordinates for direct entry. 4. On Mac, click the experiment name in the window header to rename it. The task, SO-101 arm and simulation location stay visible as context. Save remains in the toolbar, with saved, changed, pending or blocked status beside it. If it says Open workspace to save, choose Open workspace in the action bar. A retained draft is separate from a confirmed saved version. Save does not start an attempt. 5. On Mac, choose Preview goal after saving. On iPhone, connect to the selected Mac and choose Prepare simulation. Inspect the candidate and reachability message. Only an explicit, available Start action and its confirmation start an attempt. ## What to expect The draft stores a metric goal. Prepare simulation on iPhone and Preview goal on Mac give a candidate preview. It is not a completed attempt. Changing the inspection viewpoint or zoom does not change task geometry or prove reachability. ## If something goes wrong - If a coordinate is invalid, finish entering a valid value before preparing, previewing or starting the goal. If the Mac reports an unreachable target, adjust the goal and check again. - If editing is disabled while viewing a workspace result, choose Edit goal. In History, return to the workspace first. If the draft’s capability is unavailable, its contents are retained. Reconnect or return to a supported task. - If the Mac is unavailable, keep editing locally. Numeric editing does not require camera permission or physical calibration. ## Undo on Mac Use Edit → Undo or Redo to restore a goal change. While typing in a text field, those commands apply to the text you are editing. Renaming an experiment keeps its goal-change history. ## Goal meaning The Reach goal describes the tool point in the declared robot frame. A waypoint is an ordered position constraint, not collision avoidance. Object and composition support is limited to the controls and bounds supplied by that task. Moving a diagram never proves physical motion or task success. ## Lesson 1: define a task ### Example Imagine a robot arm fixed to a table. Its tip is the point we want to move. All three exercises use this same arm. The numbers and results are fictional teaching examples, not evidence from a robot run. We measure from a mark at the arm’s base. Forward is X, left is Y and up is Z. This fixed measuring system is called a **coordinate frame**. The base mark is its **origin**, where X, Y and Z are zero. Our target is 20 cm forward, directly in line with the base and 15 cm above it. We will call the task successful if the tip ends within 1 cm of that target. This allowed distance is the **tolerance**. ### Your turn Write your answer on paper or think it through before checking: 1. Complete the target in centimetres: X = \_\_, Y = \_\_, Z = \_\_. 2. The saved task uses metres. Choose the correct saved target: **A:** (20, 0, 15) m or **B:** (0.20, 0, 0.15) m. Remember: 100 cm = 1 m. 3. The tip stops 2 cm from the target. Does it meet our success rule? 4. You rotate your view of the table. Do the target’s coordinates change if our measuring system stays fixed? ### Check your reasoning 1. **X = 20 cm, Y = 0 cm, Z = 15 cm.** Y is zero because the target is neither left nor right of the base. 2. **B: (0.20, 0, 0.15) m.** Divide centimetres by 100. Option A would ask for a point 20 metres forward and 15 metres up. 3. **No.** An error of 2 cm is larger than the allowed 1 cm. We need a measured final position to check this rule. A target marker alone cannot show success. 4. **No.** Rotating the view changes how we see the table, not our fixed measuring system or target. You have specified where the tip should go and how you will judge the result. In the next exercise, distinguish that request from a prediction and a measurement. ## From this written example to a live task The fictional 1 cm final-position rule above is a teaching example. A live task has its own displayed success criterion. Roboty’s supported Reach criterion requires the tool point within 12 mm for 250 continuous simulated milliseconds. Read the rule shown with the selected task before comparing an actual result. Content ID: targets Compiled digest: 45924d1c6f479f62b07c56d076efb274871dd6550e537101cd3873bc93a96143 Language: en