### Create Web Account Mapping Example

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Example configuration for creating a mapping for a web account within the npub-map CLI wizard.

```bash
Gateway type: web
Gateway npub: your GATEWAY_NPUB
Gateway user: the web account ID (or WEBID)
User npub: the canonical npub for this user
```

--------------------------------

### Create WhatsApp Account Mapping Example

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Example configuration for creating a mapping for a WhatsApp account within the npub-map CLI wizard.

```bash
Gateway type: whatsapp
Gateway npub: your GATEWAY_NPUB
Gateway user: WhatsApp user id (e.g., 123456789@c.us)
User npub: the same canonical npub as above
```

--------------------------------

### Start Beacon Services with Bun

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Starts the beacon services, including gateways, brain, and HTTP server. Requires a GATEWAY_NPUB environment variable. A QR code for WhatsApp scanning will be displayed.

```bash
GATEWAY_NPUB=npub1yourkey bun run src/start.ts
```

--------------------------------

### Bun Install Dependencies

Source: https://github.com/humansinstitute/beacon-main/blob/main/AGENTS.md

Installs all project dependencies using the Bun package manager. This is a foundational step before running any development or build commands. It reads and applies configurations from bun.lock.

```bash
bun install
```

--------------------------------

### Run Identity Service Locally (Web Only)

Source: https://github.com/humansinstitute/beacon-main/blob/main/src/identity/README.md

This configuration starts the Identity service for Web-only usage, setting specific ports and enabling the Web adapter. It also configures an auto-approval timeout for pending requests.

```bash
# Terminal 1 (Brain):
PORT=3010 SESSION_DIR=.wwebjs_auth bun run src/start.ts

# Terminal 2 (Identity):
PORT=3011 WEB_PORT=3012 BEACON_ID_WEB=true BEACON_ID_WHATSAPP=false BEACON_AUTO=15 bun run src/identity_start.ts

# Open the Web UI:
# http://localhost:3012
```

--------------------------------

### Run Identity Service Locally (WhatsApp Only)

Source: https://github.com/humansinstitute/beacon-main/blob/main/src/identity/README.md

This configuration starts the Identity service for WhatsApp-only usage, disabling the Web adapter and enabling the WhatsApp adapter. It also specifies a session directory for WhatsApp authentication.

```bash
PORT=3011 BEACON_ID_WEB=false BEACON_ID_WHATSAPP=true SESSION_DIR=.wwebjs_auth_identity bun run src/identity_start.ts
```

--------------------------------

### Run Unified Gateway with Bun

Source: https://github.com/humansinstitute/beacon-main/blob/main/AGENTS.md

Starts the unified gateway using the Bun runtime. The GATEWAY_NPUB environment variable can be set to configure the gateway's public key. This command executes the main entrypoint at src/start.ts.

```bash
GATEWAY_NPUB=<npub> bun run src/start.ts
```

--------------------------------

### Configure Environment Variables (.env)

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Example of a .env file for configuring Beacon. Bun automatically loads .env files in the project root. Key variables include PORT, SESSION_DIR, and HEADLESS.

```dotenv
PORT=4000
SESSION_DIR=.wwebjs_auth
HEADLESS=true
```

--------------------------------

### Map User to Gateway CLI

Source: https://github.com/humansinstitute/beacon-main/blob/main/src/identity/README.md

A command-line interface helper to map a user to either the Web or WhatsApp gateway. This is crucial for routing approvals and tracking history correctly.

```bash
bun run src/cli/npub-map.ts
# Gateway type: web (or whatsapp)
# Gateway npub: your Identity GATEWAY_NPUB
# Gateway user: Web account id or WhatsApp JID
# User npub: canonical npub of the user
```

--------------------------------

### Run Modular Gateway with Bun

Source: https://github.com/humansinstitute/beacon-main/blob/main/AGENTS.md

Executes the modular gateway entrypoint using Bun. This command can optionally be provided with a GATEWAY_NPUB environment variable for specific configurations. It utilizes the src/start.ts file.

```bash
bun run src/start.ts
```

```bash
GATEWAY_NPUB=<npub> bun run src/start.ts
```

--------------------------------

### Map WhatsApp and Web Accounts with CLI

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Launches a CLI wizard to create local mappings between WhatsApp/Web accounts and user npubs. This allows conversations to thread across gateways under the same user_npub.

```bash
bun run src/cli/npub-map.ts
```

--------------------------------

### Pay LN Address using Context VM Client

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Demonstrates how to use the `payLnAddress` function from the CVM client to initiate a payment to a Lightning Network address. This function requires user's npub, a reference ID, the Lightning address, amount, and public keys for response. It relies on environment variables for CVM server communication.

```typescript
import { payLnAddress } from './brain/cvm_client/cvm_client';

await payLnAddress({
  npub: 'npubofuserwhoissendingpayment',
  refId: 'beaconmessageID',
  lnAddress: 'me@sats.com',
  amount: 10000,
  responsePubkey: 'caabbef036b063f6b29e8bc79f723aae8fb8eddc56fe198f150bae6a01741ee3',
  responseTool: 'confirmPayment',
});
```

--------------------------------

### Open Web Gateway UI

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Access the Web Gateway UI in your browser. This UI allows for multi-account management, sending messages, and viewing conversation history.

```bash
http://localhost:3010
```

--------------------------------

### Watch Mode for Unified Gateway (Bun)

Source: https://github.com/humansinstitute/beacon-main/blob/main/AGENTS.md

Runs the unified gateway in watch mode using Bun. This command automatically reloads the application when source files change, facilitating rapid development. It targets the src/start.ts entrypoint.

```bash
bun --watch src/start.ts
```

--------------------------------

### TypeScript Test Execution with Bun

Source: https://github.com/humansinstitute/beacon-main/blob/main/AGENTS.md

Executes all tests located in the src/__tests__/ directory using the Bun test runner. This command is used to validate the functionality of the codebase, assuming tests are written in TypeScript.

```bash
bun test
```

--------------------------------

### Troubleshooting: Enable Headless Browser

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Sets the HEADLESS environment variable to false, allowing the Puppeteer browser to run headfully. This is useful for debugging UI-related issues.

```bash
HEADLESS=false
```

--------------------------------

### Troubleshooting: Set System Chrome Path

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Configures Puppeteer to use a system-installed Chrome browser by setting the PUPPETEER_EXECUTABLE_PATH environment variable. Useful for resolving 'Execution context was destroyed' errors.

```bash
PUPPETEER_EXECUTABLE_PATH=/path/to/Chrome
```

--------------------------------

### Wingman Response Webhook API

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Receives responses from the Wingman service and routes them back to the original sender via WhatsApp.

```APIDOC
## POST /api/webhook/wingman_response

### Description
Routes the Wingman response back to the original sender via WhatsApp. Sanitizes control characters and collapses whitespace.

### Method
POST

### Endpoint
/api/webhook/wingman_response

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **body** (string) - The message body from Wingman.
- **beaconID** (string) - The unique identifier for the beacon conversation.

### Request Example
```json
{
  "body": "This is a response from Wingman.",
  "beaconID": "some-unique-beacon-id"
}
```

### Response
#### Success Response (200)
*No specific response body defined, assumes success if no error occurs.*

#### Response Example
*No example provided for success response.*

#### Error Response
*Error handling details not provided in the source text.*

```

--------------------------------

### HTTP API Webhook for Wingman Response

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Endpoint to route Wingman AI responses back to the original sender via WhatsApp. It sanitizes control characters and collapses whitespace in the message body.

```http
POST /api/webhook/wingman_response
Body: { "body": string, "beaconID": string }
```

--------------------------------

### Troubleshooting: Remove Session Directory

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Command to remove the session directory (default .wwebjs_auth) to resolve issues like repeated 'Client disconnected: LOGOUT'. After removal, restart the application.

```bash
rm -rf .wwebjs_auth
```

--------------------------------

### Troubleshooting: Disable Sandbox

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Sets the NO_SANDBOX environment variable to true. This is required for running Puppeteer in containerized environments like Docker or CI systems that might have sandbox restrictions.

```bash
NO_SANDBOX=true
```

--------------------------------

### HTTP API Health Check

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Endpoint to check the health status of the orchestrator. Returns a JSON object indicating the service status and npub.

```http
GET /
GET /health
```

--------------------------------

### Health Check API

Source: https://github.com/humansinstitute/beacon-main/blob/main/README.md

Checks the health of the orchestrator service and returns its status along with the service name and npub.

```APIDOC
## GET /

### Description
Checks the health of the orchestrator service.

### Method
GET

### Endpoint
/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the service is healthy.
- **service** (string) - The name of the service.
- **npub** (string) - The npub associated with the service.

#### Response Example
```json
{
  "ok": true,
  "service": "beacon-orchestrator",
  "npub": "npub1yourkey"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.