Skip to main content
The beacon register command creates an on-chain identity for your repository’s agent using the ERC-7527 standard on Base blockchain. This enables verifiable, decentralized agent identity registration.

​
Usage

beacon register [repo_path] [OPTIONS]

​
Arguments

​
repo_path
string
default:"./"
The path to the local repository to register. Defaults to the current directory.Examples:
  • ./ (current directory)
  • ./my-project
  • /home/user/repositories/my-app

​
Options

​
--chain
string
default:"base"
The blockchain to use for registration.Currently supported:
  • base - Base mainnet (default)
Example:
beacon register ./my-app --chain base
​
--agency
string
The ERC-7527 agency contract address to use for registration.Default: 0xd8b934580fcE35a11B58C6D73aDeE468a2833fa8 (Canonical Agency)Example:
beacon register --agency 0x1234567890abcdef...

​
Prerequisites

​
1. AGENTS.md file required

You must generate an AGENTS.md file before registering: 
beacon generate ./my-app
beacon register ./my-app

​
2. Git repository with remote URL

The repository must have a Git remote configured (the URL will be registered on-chain): 
cd my-app
git remote -v
# origin  https://github.com/user/my-app.git (fetch)
# origin  https://github.com/user/my-app.git (push)

​
3. Base network ETH for gas

You need ETH on Base network to pay for transaction gas fees.

​
Environment Variables

​
AGENT_PRIVATE_KEY
string
Private key for the agent wallet. If not provided, Beacon will generate a new wallet.Format: Hexadecimal string (with or without 0x prefix)Example:
export AGENT_PRIVATE_KEY="0x1234567890abcdef..."
Keep your private key secure! Never commit it to version control.
​
BASE_RPC_URL
string
default:"https://mainnet.base.org"
RPC URL for Base network. Defaults to the public Base mainnet RPC.Example:
export BASE_RPC_URL="https://base-mainnet.g.alchemy.com/v2/your-api-key"

​
How It Works

  1. Wallet Setup - Beacon uses the AGENT_PRIVATE_KEY environment variable, or generates a new wallet if not provided
  2. Repository URL Extraction - Reads the Git remote URL from .git/config
  3. Cost Calculation - Calls the agency’s getWrapOracle() function to determine registration cost
  4. Balance Check - Verifies the wallet has sufficient ETH for the transaction
  5. Registration Transaction - Calls the agency’s wrap() function to register the agent identity on-chain
  6. AGENTS.md Update - Updates the AGENTS.md file with the agent’s wallet address

​
Examples

​
Register with existing wallet

export AGENT_PRIVATE_KEY="0x1234567890abcdef..."
beacon register ./my-app
Output: 
⬛ Registering on-chain agent identity...
   💸 Registering identity via ERC-7527 (Cost: 1000000000000000 wei)...
   ✅ Registration confirmed: 0xabc123...
   📝 Updated AGENTS.md with Agent Identity.

✅ Done! Agent identity registered.

​
Register with generated wallet

beacon register ./my-app
Output: 
⬜ Registering on-chain agent identity...
   🔑 Generated new agent wallet: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1
   ⚠️  SAVE THIS PRIVATE KEY: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
   💸 Registering identity via ERC-7527 (Cost: 1000000000000000 wei)...
   ✅ Registration confirmed: 0xdef456...
   📝 Updated AGENTS.md with Agent Identity.

✅ Done! Agent identity registered.
Save the private key! If you don’t set AGENT_PRIVATE_KEY, Beacon generates a new wallet. Make sure to save the displayed private key in a secure location.

​
Register with custom agency

beacon register --agency 0x1234567890abcdef1234567890abcdef12345678

​
Register current directory

cd my-app
beacon register

​
AGENTS.md Update

After successful registration, Beacon updates your AGENTS.md file with the agent identity: Before: 
# AGENTS.md — my-app

> A sample application

## Capabilities
...
After: 
# AGENTS.md — my-app

> A sample application

**Agent Identity:** `0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1`

## Capabilities
...

​
Error Handling

​
Insufficient balance

Error: Insufficient balance on Base. Need 1000000000000000 wei, have 0 wei
Solution: Add ETH to your agent wallet on Base network.

​
Missing AGENTS.md

Error: AGENTS.md not found. Run 'generate' first.
Solution: Generate AGENTS.md before registering: 
beacon generate ./my-app
beacon register ./my-app

​
No Git remote URL

Error: Could not find repository URL in .git/config
Solution: Add a Git remote: 
git remote add origin https://github.com/user/my-app.git

​
ERC-7527 Standard

Beacon uses the ERC-7527 standard for on-chain agent identity:
  • Agency Contract: Manages agent registrations and wrapping
  • Wrap Function: Creates a new agent identity NFT
  • Oracle Function: Calculates registration cost (premium + fee)
Default Canonical Agency: 
0xd8b934580fcE35a11B58C6D73aDeE468a2833fa8

​
Security Best Practices

  1. Never commit private keys - Use environment variables, never hardcode keys
  2. Use a dedicated agent wallet - Don’t use your personal wallet for agent registration
  3. Verify contract addresses - Double-check agency addresses before registering
  4. Test on testnets first - Consider testing on Base Sepolia before mainnet registration
  5. Backup your private key - Store it securely in a password manager or hardware wallet

​
Source Code Reference

The register command implementation can be found in:
  • Command definition: /home/daytona/workspace/source/src/main.rs:74-81
  • Execution logic: /home/daytona/workspace/source/src/main.rs:474-478
  • Identity module: /home/daytona/workspace/source/src/identity.rs:23-115
  • generate - Generate AGENTS.md before registering
  • validate - Validate AGENTS.md after registration

Build docs developers (and LLMs) love

Get started for freeTalk to us