# 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](https://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](https://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.

### Docker (recommended)

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

```bash
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:

```bash
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:

```bash
curl http://localhost:8000/up
```

For deeper Docker detail (MySQL profile, volumes, logs) see [self-hosted-docker.md](./self-hosted-docker.md). For license placement, test mode, and the update window see [licensing.md](./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):

```bash
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):

```bash
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:

```bash
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:

```bash
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](./mcp.md).

## 6. Receive replies

For inbound messages and delivery status updates, point Twilio's webhooks at your Beacon install. See [webhooks.md](./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

- [API reference](./api.md) — every HTTP endpoint
- [MCP reference](./mcp.md) — every tool, resource, and prompt
- [Configuration](./configuration.md) — every environment variable
- [Webhooks](./webhooks.md) — inbound SMS and delivery status
- [Licensing](./licensing.md) — `beacon.license`, test mode, updates
- [Troubleshooting](./troubleshooting.md) — when something goes sideways