# BYO Local Connectors

Source: https://docs.generalaugment.com/channels/local-connectors/
Description: Attach tenant-owned Macs, VMs, coding sandboxes, or private hosts as governed General Augment capabilities.

General Augment can govern capabilities that run outside the hosted platform. A local
connector is a small tenant-operated HTTP service on a Mac, VM, coding sandbox, or
private network host.

The private host owns execution. General Augment owns policy, approvals, audit,
redaction, rate limits, and the Hermes-facing tool surface.

```text
Tenant-owned host -> local connector -> General Augment -> governed tools -> Hermes
```

Hermes never sees connector URLs, shell commands, local file paths, provider tokens,
Apple IDs, phone numbers, or adapter-specific commands. It only sees General
Augment-governed tool schemas.

Known surfaces can use dedicated governed tools, such as `imessage_search_history`
and `imessage_send_message`. Generic connectors use `local_connector_action`, which
invokes only explicitly configured connector capabilities and requires approval before
dispatch.

Setup model

## Use a helper or hand it to an agent

For local iMessage, start with the npm helper. It checks the Mac, prints safe
project config, and can write a coding-agent prompt that performs the repo-specific
setup and smoke verification.

```bash
npx @general-augment/local-imessage setup --project <project-slug> --write-prompt --write-config
```

`--write-config` writes `general-augment-imessage-connector.json` with the
`local_connectors` and `enabled_tool_ids` fields your project update uses. Review the
opaque refs, then save the same starter config from the dashboard Surfaces page or
apply it through your admin API path.

## Contract

Every connector should expose a secret-free health endpoint:

```http
GET /health
```

Expected safe shape:

```json
{
  "ok": true,
  "kind": "imessage",
  "capabilities": ["imessage.search_history", "imessage.send_message"],
  "send_enabled": false
}
```

General Augment action calls use:

```http
POST /v1/actions/{capability}
```

At runtime, General Augment calls that action through either a first-party governed
tool or the generic `local_connector_action` tool. Keep capability names narrow, for
example `private.lookup` or `sandbox.run_tests`, and avoid catch-all connector actions.

Run the generic contract smoke before connector-specific checks:

```bash
uv run python scripts/local-connector-contract-smoke.py \
  --url http://127.0.0.1:8765 \
  --kind imessage \
  --capability imessage.search_history \
  --capability imessage.send_message
```

Dashboard and support views can read safe status through:

```http
GET /api/v1/admin/projects/{project_id}/local-connectors/status
```

When the user explicitly asks to check a connector, General Augment can run the
secret-free health action:

```http
POST /api/v1/admin/projects/{project_id}/local-connectors/{connector_name}/health-check
```

The health action reports reachability, latency, advertised capabilities, and the
send-enabled flag when present. It does not return connector URLs, credential
placeholder names, local handles, local paths, or connector response bodies.

## Configure

```yaml
connectors:
  local:
    - name: mac_imessage
      kind: imessage
      url: https://connector.example.com
      auth: Bearer ${{ credentials.local_connector_token }}
      capabilities:
        - imessage.get_recent_thread
        - imessage.search_history
        - imessage.send_message
      policy:
        allowed_contact_refs:
          - contact_primary
        require_approval_for_send: true

tools:
  builtin:
    - imessage_get_recent_thread
    - imessage_search_history
    - imessage_send_message
```

Use opaque refs such as `contact_primary` or `thread_primary`. Keep real handles,
tokens, transcripts, and local paths in `.env.local`, the tenant host, or a secret
manager.

## Governance

- Read tools are scoped by connector policy.
- Write tools require approval when the tool definition marks them sensitive.
- Tool-call audit rows are redacted before storage.
- Runtime policy summaries show connector kind, capabilities, and policy counts, not
private endpoints or secrets.

## Patterns Beyond iMessage

Use the same contract for any tenant-owned capability host:

| Pattern | Connector owns | General Augment exposes |
| --- | --- | --- |
| Private VM | VM credentials, process manager, local network routes | Health, approved actions, redacted results |
| Coding sandbox | Repo checkout, test runner, package caches, build tools | Bounded code/test tools with audit and approvals |
| Private network API | VPN/VPC access, internal service auth | Narrow API actions without leaking internal hosts |
| Desktop automation | Local app session, screen/filesystem permissions | Governed commands and redacted summaries |
| Tenant-owned provider capacity | Provider account keys, quotas, spend controls | Safe capability tools and per-tenant usage evidence |

Agent setup prompts should always say: keep private credentials and local handles on the
tenant host, expose only opaque refs in project config, run `GET /health` and the generic
contract smoke first, then enable writes only behind General Augment approvals.

For iMessage setup, use [Connect A Mac For iMessage](/channels/imessage-mac/).