> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RunMesh

> Link, list, configure, rename, and revoke private mesh nodes

## Device Link Flow

Device linking starts before normal user auth because the device does not have an approved identity yet.

| Method | Path                               | Auth         | Description                                            |
| ------ | ---------------------------------- | ------------ | ------------------------------------------------------ |
| `POST` | `/v1/runmesh/devices/link/start`   | none         | Create a short-lived link code for a device public key |
| `POST` | `/v1/runmesh/devices/link/poll`    | none         | Poll a link code until approved or expired             |
| `POST` | `/v1/runmesh/devices/link/approve` | user/API key | Approve a pending code into the current org            |

### Start Link

<ParamField body="publicKey" type="string" required>
  Device public key.
</ParamField>

<ParamField body="deviceLabel" type="string">
  Human-readable device label.
</ParamField>

<ParamField body="os" type="string">
  Client OS, such as `macos`.
</ParamField>

<ParamField body="appVersion" type="string">
  Client app version.
</ParamField>

```bash cURL theme={null}
curl -X POST https://api.runtools.ai/v1/runmesh/devices/link/start \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "device-public-key",
    "deviceLabel": "Office Workstation",
    "os": "macos"
  }'
```

```json 201 Created theme={null}
{
  "data": {
    "code": "ABCD12",
    "url": "https://runtools.ai/devices/link",
    "expiresAt": "2026-05-10T12:00:00.000Z"
  }
}
```

## Authenticated Node APIs

All routes below require normal auth.

| Method   | Path                                | Scope           | Description                     |
| -------- | ----------------------------------- | --------------- | ------------------------------- |
| `GET`    | `/v1/runmesh/overview`              | `runmesh:read`  | Node counts for the org         |
| `GET`    | `/v1/runmesh/nodes`                 | `runmesh:read`  | List visible nodes              |
| `GET`    | `/v1/runmesh/nodes/{id}`            | `runmesh:read`  | Get one node                    |
| `GET`    | `/v1/runmesh/nodes/{id}/config`     | `runmesh:read`  | Generate peer config for a node |
| `PATCH`  | `/v1/runmesh/nodes/{id}`            | `runmesh:write` | Rename a node                   |
| `DELETE` | `/v1/runmesh/nodes/{id}`            | `runmesh:write` | Revoke a node                   |
| `POST`   | `/v1/runmesh/nodes/{id}/revoke`     | `runmesh:write` | Revoke a node                   |
| `GET`    | `/v1/runmesh/audit`                 | `runmesh:read`  | List RunMesh audit events       |
| `GET`    | `/v1/runmesh/devices/{id}/activity` | `activity:read` | Activity for one device         |

<ParamField query="all" type="boolean">
  Include all visible org nodes.
</ParamField>

<ParamField query="owner" type="string">
  Use `owner=me` to list only nodes owned by the current user.
</ParamField>

```bash cURL theme={null}
curl "https://api.runtools.ai/v1/runmesh/nodes?owner=me" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

## Local Device Agents

Create a local device agent with `executionMode: "local-mac"` and a `targetDeviceId`. Runs can be started from any client, but the work executes on the bound device through RunMesh.

```json theme={null}
{
  "slug": "code-on-my-mac",
  "executionMode": "local-mac",
  "targetDeviceId": "node_abc123",
  "tools": ["exec_command", "write_stdin", "apply_patch", "view_image", "web_search"]
}
```