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

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