# Laserreach Local AI Agent Setup Handoff

Use this checklist when a customer wants Claude Cowork, Codex, or another local AI agent to work with Laserreach.

## Recommended Mode

Use local-agent API access first. The external agent calls Laserreach APIs directly with its own memory and model provider. Leave Laserreach-hosted run control off unless the customer explicitly wants the local agent to start, steer, cancel, retry, or prune Laserreach-hosted runs.

## Owner Setup

1. Sign in at https://www.laserreach.com.
2. Open the correct organization.
3. Go to Settings > External Agents.
4. Name the token after the tool, for example `Claude Cowork` or `Codex`.
5. Choose `Use self-governed setup` when the agent should send and publish without per-action human approval.
6. Use custom scopes when human approvals should remain required.
7. Leave `Allow Laserreach-hosted run control` off for the normal setup.
8. Leave `hosted-ai:use` off when Claude, Codex, or another local model supplies
   signal reasoning and outreach copy.
8. Create the token.
9. Copy the complete setup block immediately. The token is shown once.

## Give This To The Agent

Replace the placeholders with the values from the copied setup block.

```text
You are connected to Laserreach through an external-agent token.

Use these headers on every Laserreach API request:
Authorization: Bearer <external_agent_token>
X-Org-ID: <org_id>

Start here:
GET https://api.laserreach.com/api/abm/agent/capabilities

ICP endpoint:
https://api.laserreach.com/api/abm/icps

Signal endpoint:
https://api.laserreach.com/api/abm/signals

Token self-revocation endpoint:
DELETE https://api.laserreach.com/api/abm/agent/token

HubSpot outreach sync endpoint:
https://api.laserreach.com/api/abm/crm/hubspot/outreach-sync

Local MCP/webhook helper:
https://github.com/tcmartin/laserreach-local-agent-mcp

Portable open-source AI skill:
https://github.com/tcmartin/laserreach-local-agent-mcp/tree/main/skills/laserreach

Single-file Codex webhook bridge:
https://www.laserreach.com/examples/laserreach-codex-webhook-bridge.mjs

Use the capabilities response as the source of truth for available routes.
Use Laserreach for scoped API actions, account context, memory, policies, workspace files, schedules, recommendations, CRM sync, browser sessions, content, ads, and intel.
Do not start, steer, cancel, retry, or prune Laserreach-hosted runs unless the user explicitly asks and this token includes agent-runs:control.
Do not call model-backed endpoints unless the token includes `hosted-ai:use`.
Without that scope, source collection stores raw signals and does not queue
Laserreach-hosted scoring. Score them locally and write the assessment back.
Use `laserreach_assess_signal` for local scoring and
`laserreach_create_local_sequence` for local copy. The sequence tool forces
`use_ai=false`.
Use the local model to assess raw signals and save results with PATCH /api/abm/signals/{signal_id}/assessment.
Use require_icp_match=true and min_score=0.5 for the normal actionable queue.
Starting a sequence requires outreach:send and does not require agent-runs:control.
When the capabilities response reports approval_mode=self_governed, execute allowed sends and publishes without waiting for human approval.
Account caps, sender and connector checks, business hours, deduplication, kill switches, scopes, and token-attributed audit logs remain enforced.
Account settings, caps, connector credentials, kill switches, and governance
remain user-managed.
Prefer local planning and memory.
For local-agent outreach, log CRM activity with the HubSpot outreach sync endpoint after the local agent sends or stages a message. Test with `dry_run: true` before writing CRM records.
```

## First Connection Test

Run this from a terminal or ask the agent to run it.

```bash
curl "https://api.laserreach.com/api/abm/agent/capabilities" \
  -H "Authorization: Bearer <external_agent_token>" \
  -H "X-Org-ID: <org_id>"
```

Expected result: JSON with capability groups and route URLs. If the response is `401` or `403`, verify the token and org header.

## Optional Local MCP, Webhook, And Cron Runner

Use this when Claude Desktop, Codex, or another local agent should call Laserreach tools, react to Laserreach events, receive events from HubSpot, Zapier, Make, n8n, or poll on a schedule.

```bash
npx -y github:tcmartin/laserreach-local-agent-mcp install-skill --target codex
npm install -g github:tcmartin/laserreach-local-agent-mcp
export LASERREACH_AGENT_TOKEN="<external_agent_token>"
export LASERREACH_ORG_ID="<org_id>"
export LASERREACH_API_BASE="https://api.laserreach.com"
export LASERREACH_WEBHOOK_SECRET="<shared_webhook_secret>"

# Test API access.
laserreach-local-agent capabilities

# Claude Desktop MCP command:
npx -y github:tcmartin/laserreach-local-agent-mcp mcp

# Local-agent HubSpot logging tool:
# laserreach_sync_hubspot_outreach with dry_run: true first.

# Webhook and cron runner:
laserreach-local-agent init
laserreach-local-agent serve --config ./laserreach.local-agent.config.json
```

Expose the local listener with a tunnel such as ngrok only after `LASERREACH_WEBHOOK_SECRET` is set.

## End-To-End Checks

1. The setup guide is reachable at https://www.laserreach.com/docs/external-agent-setup.
2. The owner can create a token from Settings > External Agents.
3. The copied setup block includes `Authorization`, `X-Org-ID`, capabilities,
   ICP, signal, and token self-revocation URLs.
4. The copied setup block includes the HubSpot outreach sync endpoint.
5. `GET /api/abm/agent/capabilities` returns JSON for the token and org.
6. The connected agent can summarize the returned capabilities without using unstated routes.
7. A self-governed token reports `human_approval_bypassed: true` and `caps_enforced: true`.
8. With run control off, the agent does not start, steer, cancel, retry, or prune hosted runs.
9. With `hosted-ai:use` off, model-backed preparation, scoring, generation, and
   optimization return `403`.
10. A locally generated sequence created through the MCP helper stores every
    step with `use_ai=false`.
9. A dry-run call to `/api/abm/crm/hubspot/outreach-sync` returns a plan before any CRM writes.
10. If the MCP/webhook helper is used, the local listener returns `202 Accepted` for a valid event and writes an event record under `~/.laserreach-local-agent`.
11. The customer can revoke the token from Settings > External Agents or the
    token can revoke itself with `DELETE /api/abm/agent/token`.

## Message To Send A Customer Or Contractor

```text
Please follow this Laserreach setup guide:
https://www.laserreach.com/docs/external-agent-setup

Use the recommended local-agent API access mode.
Do not enable Laserreach-hosted run control unless we explicitly decide the agent should control hosted Laserreach runs.
After the token is created, paste the complete setup block into Claude Cowork, Codex, or your local agent. Ask it to start by calling the capabilities URL and to use only the routes returned by that response.

For local MCP, webhook, or cron automation, use the public helper repo linked in the guide.
```

## Security Notes

- Store the token in the connected tool or a local secret manager.
- Do not paste the token into shared documents, tickets, or public chats.
- Revoke the token when access is no longer needed.
- Rotate the token if it was pasted into the wrong place.
- Self-governed mode removes human approvals, not account caps or execution controls.
- Keep hosted run control separate from normal local-agent workflows.
- Keep `hosted-ai:use` off when the customer-local model performs the reasoning
  and copywriting.