BYO Local Connectors

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.

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.

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:

GET /health

Expected safe shape:

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

General Augment action calls use:

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:

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:

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:

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

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.