Beacon
Documentation

Start here

Install

Reference

Operate

Start here

Quickstart — Give your agent a phone number in 5 minutes

This walks you from the ApexCode license portal to your agent sending its first text. You do not clone a GitHub repo.

You will need:

  • A Beacon license from apexcode.dev/beacon (the portal email has the files and credentials)
  • Docker and Docker Compose (Docker path), or PHP 8.3+ and Composer (Composer path)
  • A Twilio account with at least one available phone number (or credits to buy one)
  • An MCP-aware client (Claude Code is shown here)

If you only want to try Beacon without Twilio, use test mode — append _test to any API key and Beacon simulates Twilio without contacting it. Live API keys still need beacon.license in place.

1. Get your license files

Checkout at apexcode.dev/beacon. Polar sends you to the license portal. From there:

  1. Download the signed beacon.license file.
  2. Copy the GHCR pull token (Docker) or Composer credentials (email + license key).
  3. Keep the Compose bundle links — docker-compose.yml and .env.example.

Current release: 0.3.3-beta. Image: ghcr.io/apxcde/beacon:0.3.3-beta. Composer packages: https://packages.apexcode.dev.

2. Boot the stack

Self-hosted Docker is a Compose bundle (docker-compose.yml + .env.example, HTTP on port 8000), not a naked docker run. Pick one path.

From an empty directory. The same files are on your license portal:

mkdir beacon && cd beacon
curl -fsSL https://apexcode.dev/beacon/docker-compose.yml -o docker-compose.yml
curl -fsSL https://apexcode.dev/beacon/env.example -o .env.example
cp .env.example .env

echo '<token-from-your-license-portal>' | docker login ghcr.io -u apxcde-distrib --password-stdin
docker compose up -d

docker compose cp ./beacon.license app:/var/www/html/storage/app/beacon.license

Composer

Install the Laravel project from the private registry, then boot the same Compose stack from that directory:

composer config --auth \
    http-basic.packages.apexcode.dev \
    <email-from-your-license-portal> \
    <license-key>

composer create-project apxcde/beacon my-beacon \
    --repository='{"type":"composer","url":"https://packages.apexcode.dev"}'

cd my-beacon
cp .env.example .env
cp ./beacon.license storage/app/beacon.license

docker compose up -d

Wait for the nginx container to report healthy. The full first-boot sequence (key generation, migrations, storage symlink) takes about 30 seconds.

Confirm the app is up:

curl http://localhost:8000/up

For deeper Docker detail (MySQL profile, volumes, logs) see self-hosted-docker.md. For license placement, test mode, and the update window see licensing.md.

3. Run first-run setup

Open http://localhost:8000 in a browser. The setup wizard will walk you through:

  1. Workspace — create the default team
  2. Twilio credentials — paste your Account SID and Auth Token (stored encrypted, per-team in the database)
  3. Business number — either enter a number you already own on Twilio, or search and buy one directly from the wizard
  4. API key — generate the team's first API key

Copy the API key when it is shown — it is only displayed once.

4. Send your first text from curl

Test mode (no Twilio call, append _test to your key):

curl -X POST http://localhost:8000/api/text \
  -H "X-API-Key: beacon_YOUR_KEY_HERE_test" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "message": "Hello from Beacon"
  }'

Live send (omit the _test suffix, keep beacon.license installed, and use a number Twilio can reach):

curl -X POST http://localhost:8000/api/text \
  -H "X-API-Key: beacon_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "message": "Hello from Beacon"
  }'

The response includes a threadId. List threads to confirm:

curl http://localhost:8000/api/threads \
  -H "X-API-Key: beacon_YOUR_KEY_HERE"

5. Connect your agent over MCP

Register Beacon's MCP server with Claude Code:

claude mcp add beacon http://localhost:8000/api/mcp \
  --transport http \
  --scope user \
  --header "X-API-Key: beacon_YOUR_KEY_HERE"

In any new Claude Code session you can now ask things like:

Find any contacts named Sam in Beacon and summarize the last thread with each.

Send a follow-up to +15551234567 saying their order shipped.

The full tool, resource, and prompt catalog is in mcp.md.

6. Receive replies

For inbound messages and delivery status updates, point Twilio's webhooks at your Beacon install. See webhooks.md for the URLs to configure and how to expose your local installation via a tunnel during development.

If you are only sending OTPs or one-way messages, you can skip this step for now.

What's next

Raw markdown · llms.txt