Connect your own 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 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 provides the index, complete Markdown 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:

/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.

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:

{"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.<operation> 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:

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. 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.

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:

{
  "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 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:

{
  "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:

{ "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.