Skip to main content

​
System requirements

Beacon is a Rust binary with minimal dependencies. It runs on:
  • Operating systems: Linux (x86_64, ARM64), macOS (Intel, Apple Silicon)
  • Dependencies: None (statically linked binary)
  • Disk space: ~10 MB
  • RAM: Minimal (typically under 50 MB during execution)
Windows support is not currently available, but you can use Docker or WSL2 with the Linux binary.
The fastest way to install Beacon is using the official install script: 
curl -fsSL https://raw.githubusercontent.com/DavidNzube101/beacon/master/install.sh | sh
This script:
  • Detects your platform (Linux/macOS, x86_64/ARM64)
  • Downloads the latest release binary
  • Installs to /usr/local/bin/beacon
  • Requires sudo if /usr/local/bin isn’t writable

​
Install a specific version

curl -fsSL https://raw.githubusercontent.com/DavidNzube101/beacon/master/install.sh | sh -s -- beacon latest
Or specify a version number: 
curl -fsSL https://raw.githubusercontent.com/DavidNzube101/beacon/master/install.sh | sh -s -- beacon 0.2.4

​
Custom installation name

If you already have a binary named beacon, you can install with a different name: 
curl -fsSL https://raw.githubusercontent.com/DavidNzube101/beacon/master/install.sh | sh -s -- beacon-ai
The install script will detect if a non-Beacon binary named beacon exists and prompt you to choose a different name to avoid conflicts.

​
Docker

Run Beacon as a web API using Docker: 
docker run -p 8080:8080 \
  -e GEMINI_API_KEY=your_key_here \
  ghcr.io/davidnzube101/beacon
This starts the Beacon API server on port 8080 with the following endpoints:
  • GET /health — Health check
  • POST /generate — Generate AGENTS.md from a repository
  • POST /validate — Validate an AGENTS.md file

​
Docker with multiple providers

Set environment variables for all AI providers you want to use: 
docker run -p 8080:8080 \
  -e GEMINI_API_KEY=your_gemini_key \
  -e CLAUDE_API_KEY=your_claude_key \
  -e OPENAI_API_KEY=your_openai_key \
  -e REDIS_URL=redis://your-redis:6379 \
  ghcr.io/davidnzube101/beacon
The Docker image requires REDIS_URL to be set for rate limiting. If you don’t have Redis, use the CLI binary instead.

​
Docker Compose example

docker-compose.yml
version: '3.8'
services:
  beacon:
    image: ghcr.io/davidnzube101/beacon
    ports:
      - "8080:8080"
    environment:
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
  
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

​
Build from source

If you want to build Beacon yourself or contribute to development:
1

Install Rust

Install the Rust toolchain using rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Verify installation:
rustc --version
cargo --version
2

Clone the repository

git clone https://github.com/DavidNzube101/beacon.git
cd beacon
3

Build the binary

Build the release binary:
cargo build --release
The compiled binary will be at target/release/beacon.
4

Install globally (optional)

Copy to your PATH:
sudo cp target/release/beacon /usr/local/bin/
Or install using Cargo:
cargo install --path .

​
Verify installation

Check that Beacon is installed correctly: 
beacon --version
You should see output like: 
beacon 0.2.4
View available commands: 
beacon --help

⬛ Make any repo agent-ready. Instantly.

Usage: beacon <COMMAND>

Commands:
  generate  Generate an AGENTS.md file for a repository
  validate  Validate an AGENTS.md file
  serve     Run Beacon as a web API
  register  Register an on-chain agent identity
  help      Print this message or the help of the given subcommand(s)

​
Set up your AI provider key

Beacon requires an API key from one of the supported providers. Set it as an environment variable: 
export GEMINI_API_KEY=your_key_here
Add to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist across sessions:
~/.zshrc
echo 'export GEMINI_API_KEY=your_key_here' >> ~/.zshrc
source ~/.zshrc
You can also pass the API key directly using the --api-key flag when running beacon generate. See the generate command reference for details.

​
Troubleshooting

​
Permission denied when installing

If you see a permission error during installation: 
sudo chown -R $USER /usr/local/bin
Or install to a user-writable directory: 
mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/DavidNzube101/beacon/master/install.sh | sh
mv /tmp/beacon_* ~/.local/bin/beacon
Then add ~/.local/bin to your PATH: 
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

​
Binary not found after installation

Verify /usr/local/bin is in your PATH: 
echo $PATH
If not, add it: 
export PATH="/usr/local/bin:$PATH"

​
Docker Redis connection error

If the Docker container fails to start with a Redis connection error, make sure you’ve set REDIS_URL: 
docker run -p 8080:8080 \
  -e GEMINI_API_KEY=your_key \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  ghcr.io/davidnzube101/beacon

​
Unsupported architecture error

If the install script reports an unsupported architecture, check your system: 
uname -s  # Should be Linux or Darwin
uname -m  # Should be x86_64, aarch64, or arm64
Currently supported platforms:
  • beacon-linux-x86_64
  • beacon-linux-arm64
  • beacon-macos-x86_64
  • beacon-macos-arm64

​
Next steps

Quickstart guide

Generate your first AGENTS.md file

Generate command

Learn about all generation options

AI providers

Choose the right AI provider for your needs

Docker deployment

Deploy Beacon as a production API

Build docs developers (and LLMs) love

Get started for freeTalk to us