beads/docs/AGENT_MAIL_DEPLOYMENT.md

Agent Mail Deployment - Last Mile Steps

Complete step-by-step guide to deploy Agent Mail across all 12 beads-enabled workspaces.

Prerequisites

• ✅ MCP Agent Mail package installed at ~/src/mcp_agent_mail/
• ✅ beads integration code completed (just finished)
• ✅ Helper scripts created in scripts/
• ✅ direnv installed (brew install direnv)
• ✅ direnv hook added to shell config

Architecture Overview

One Server, Three Channels:

• Agent Mail Server: Single instance on http://127.0.0.1:8765
• beads.dev: 5 beads workers communicate here
• vc.dev: 5 vc workers communicate here
• wyvern.dev: 3 wyvern workers communicate here

Total: 13 workspaces (12 repos + main beads for version bump)

Step 1: Version Bump (5 minutes)

Since Agent Mail integration is brand new, bump beads version first.

cd ~/src/fred/beads

# Determine new version (check current first)
./bd --version
# Example output: bd version 0.16.0

# Bump to next version
./scripts/bump-version.sh 0.23.0 --commit

# Push to trigger release
git push origin main
git push origin v0.23.0

Rationale: All workspaces should use the new version with Agent Mail support.

Step 2: Start Agent Mail Server (2 minutes)

cd ~/src/fred/beads

# Start server in background
./scripts/start-agent-mail-server.sh

# Expected output:
# ✅ Agent Mail server started successfully!
#    PID: 12345
#    Health: http://127.0.0.1:8765/health
#    Web UI: http://127.0.0.1:8765/mail

# Verify server health
curl http://127.0.0.1:8765/health
# Expected: {"status": "healthy"}

Troubleshooting:

• If port 8765 in use: lsof -i :8765 then kill <PID>
• If server fails: Check ~/agent-mail.log for errors
• If venv missing: See installation steps in docs/AGENT_MAIL_QUICKSTART.md

Step 3: Configure All Workspaces (10 minutes)

Run setup script in each workspace to create .envrc files.

3a. Configure 5 beads repos

# Main beads repo
cd ~/src/beads
../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# cino/beads fork
cd ~/src/cino/beads
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# dave/beads fork
cd ~/src/dave/beads
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# emma/beads fork
cd ~/src/emma/beads
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# fred/beads fork (current repo)
cd ~/src/fred/beads
./scripts/setup-agent-mail-workspace.sh .
direnv allow

Expected .envrc content:

# Agent Mail Configuration
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
export BEADS_AGENT_NAME=fred-beads-macbook  # (varies by workspace/hostname)
export BEADS_PROJECT_ID=beads.dev

3b. Configure 5 vc repos

# Main vc repo (if standalone exists)
cd ~/src/vc
../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# cino/vc
cd ~/src/cino/vc
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# dave/vc
cd ~/src/dave/vc
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# fred/vc
cd ~/src/fred/vc
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# (One more standalone vc if it exists - adjust path as needed)

Expected PROJECT_ID: vc.dev

3c. Configure 3 wyvern repos

# Main wyvern repo
cd ~/src/wyvern
../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# cino/wyvern
cd ~/src/cino/wyvern
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

# fred/wyvern
cd ~/src/fred/wyvern
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
direnv allow

Expected PROJECT_ID: wyvern.dev

Step 4: Upgrade beads Binary Everywhere (5 minutes)

After version bump in Step 1, upgrade all workspaces to new version.

# Wait for GitHub release to build (check https://github.com/steveyegge/beads/releases)
# Or build locally if impatient

# Option 1: Install from release (when ready)
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash

# Option 2: Build locally and copy to all repos
cd ~/src/fred/beads
go build -o bd ./cmd/bd

# Copy to other repos (example for beads repos)
cp bd ~/src/beads/bd
cp bd ~/src/cino/beads/bd
cp bd ~/src/dave/beads/bd
cp bd ~/src/emma/beads/bd

# Verify new version includes Agent Mail support
cd ~/src/fred/beads
./bd --version
# Expected: bd version 0.23.0 (or whatever you bumped to)

./bd info --json | grep -i agent
# Expected: JSON output showing agent_mail config

Step 5: Document Configuration (2 minutes)

Add Agent Mail config to each workspace's AGENTS.md (if applicable). Agents need these instructions before testing.

Example for vc repos:

cd ~/src/fred/vc

# Add to AGENTS.md (or create if missing)
cat >> AGENTS.md <<'EOF'

## Agent Mail Configuration

This workspace participates in multi-agent coordination via MCP Agent Mail.

**Channel**: vc.dev (shared with all vc workers)
**Server**: http://127.0.0.1:8765
**Agent Name**: fred-vc-<hostname>

**Configuration**: Loaded automatically via `.envrc` (direnv)

**Tightly coupled workers**:
- ~/src/vc
- ~/src/cino/vc
- ~/src/dave/vc
- ~/src/fred/vc
- (one more standalone)

All vc workers coordinate issue reservations in real-time (<100ms latency).

**Cross-project coordination**: vc → beads bugs filed via git/PRs (not Agent Mail messaging)

See `docs/AGENT_MAIL_MULTI_WORKSPACE_SETUP.md` for details.
EOF

Repeat for beads and wyvern workspaces with appropriate channel names.

Step 6: Test Same-Channel Coordination (5 minutes)

Verify agents in same channel can see each other's reservations.

6a. Test vc.dev channel (2 vc repos)

Terminal 1 - fred/vc:

cd ~/src/fred/vc

# Verify env vars
echo $BEADS_PROJECT_ID  # Expected: vc.dev
echo $BEADS_AGENT_NAME  # Expected: fred-vc-<hostname>

# Create test issue and reserve it
bd create "Test Agent Mail coordination" -p 2 -t task
# Example output: bd-test42

bd update bd-test42 --status in_progress
# Expected: ✅ Reserved bd-test42 for fred-vc-macbook

Terminal 2 - cino/vc:

cd ~/src/cino/vc

# Verify env vars
echo $BEADS_PROJECT_ID  # Expected: vc.dev
echo $BEADS_AGENT_NAME  # Expected: cino-vc-<hostname>

# Try to claim same issue
bd update bd-test42 --status in_progress
# Expected: ❌ Error - bd-test42 already reserved by fred-vc-macbook

Success! Collision prevented across different repos in same channel.

Terminal 1 - Cleanup:

cd ~/src/fred/vc
bd close bd-test42 "Test complete"
# Expected: ✅ Reservation released

6b. Test channel isolation

Verify agents in different channels DON'T interfere.

Terminal 1 - fred/beads (beads.dev):

cd ~/src/fred/beads
bd create "Test channel isolation" -p 2
# Example: Created bd-test1

bd update bd-test1 --status in_progress
# Expected: Success

Terminal 2 - fred/vc (vc.dev):

cd ~/src/fred/vc
bd create "Test channel isolation" -p 2
# Example: Created bd-test2

bd update bd-test2 --status in_progress
# Expected: Success (no conflict - different channel!)

Both reservations succeed because they're in different channels.

Step 7: Monitor All Channels (2 minutes)

cd ~/src/fred/beads

# Check overall status
./scripts/agent-mail-status.sh

# Expected output:
# === Agent Mail Status ===
# Server Process: ✅ Running (PID: 12345)
# Server Health: ✅ OK
# Active Projects:
#   • beads.dev
#   • vc.dev
#   • wyvern.dev
# Active File Reservations:
#   (list of current reservations across all channels)

# Open Web UI for visual monitoring
open http://127.0.0.1:8765/mail

Step 8: Make Server Auto-Start on Reboot (Optional, 5 minutes)

Use macOS launchd for automatic server startup.

# Create launchd plist
cat > ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.mcp-agent-mail</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/stevey/src/mcp_agent_mail/.venv/bin/python</string>
        <string>-m</string>
        <string>mcp_agent_mail.cli</string>
        <string>serve-http</string>
        <string>--host</string>
        <string>127.0.0.1</string>
        <string>--port</string>
        <string>8765</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/stevey/src/mcp_agent_mail</string>
    <key>StandardOutPath</key>
    <string>/Users/stevey/agent-mail.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/stevey/agent-mail-error.log</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

# Load service
launchctl load ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist

# Verify loaded
launchctl list | grep mcp-agent-mail
# Expected: Shows PID and status

# Test restart
sudo reboot  # (or just log out/in)
# After reboot, verify server auto-started:
curl http://127.0.0.1:8765/health

Step 9: Auto-Start on Reboot (Optional, 5 minutes)

Use macOS launchd for automatic server startup.

# Create launchd plist
cat > ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.mcp-agent-mail</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/stevey/src/mcp_agent_mail/.venv/bin/python</string>
        <string>-m</string>
        <string>mcp_agent_mail.cli</string>
        <string>serve-http</string>
        <string>--host</string>
        <string>127.0.0.1</string>
        <string>--port</string>
        <string>8765</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/stevey/src/mcp_agent_mail</string>
    <key>StandardOutPath</key>
    <string>/Users/stevey/agent-mail.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/stevey/agent-mail-error.log</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

# Load service
launchctl load ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist

# Verify loaded
launchctl list | grep mcp-agent-mail
# Expected: Shows PID and status

# Test restart
sudo reboot  # (or just log out/in)
# After reboot, verify server auto-started:
curl http://127.0.0.1:8765/health

Step 10: Verification Checklist

Run through this checklist to confirm deployment success.

✅ Server Health

• curl http://127.0.0.1:8765/health returns {"status": "healthy"}
• PID file exists: cat ~/agent-mail.pid
• Process running: ps -p $(cat ~/agent-mail.pid)
• Logs clean: tail ~/agent-mail.log (no errors)

✅ Workspace Configuration

• All 13 workspaces have .envrc files
• All .envrc files have correct BEADS_PROJECT_ID:
  • 5 beads repos → beads.dev
  • 5 vc repos → vc.dev
  • 3 wyvern repos → wyvern.dev
• All workspaces allowed: direnv allow in each
• Env vars load automatically when cd-ing into workspace

✅ beads Binary

• All workspaces using new version with Agent Mail support
• bd --version shows 0.23.0+ everywhere
• bd info --json | grep agent_mail shows config

✅ Multi-Agent Coordination

• Same channel: Reservation conflict works (tested in Step 6a)
• Different channels: No interference (tested in Step 6b)
• Web UI shows all 3 channels: http://127.0.0.1:8765/mail
• Status script works: ./scripts/agent-mail-status.sh

✅ Persistence

• Server survives reboot (if launchd configured in Step 8)
• Reservations cleared on server restart (expected behavior)
• Agents re-register automatically after server restart

Common Issues

Issue: direnv not loading .envrc

Symptoms:

cd ~/src/fred/beads
echo $BEADS_PROJECT_ID
# (empty output)

Fix:

# Check direnv hook installed
grep direnv ~/.zshrc
# Should see: eval "$(direnv hook zsh)"

# If missing, add it
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc

# Allow .envrc
cd ~/src/fred/beads
direnv allow

Issue: Agent names collide

Symptoms: Two workspaces use same BEADS_AGENT_NAME

Fix: Edit .envrc to make agent names unique:

# Bad (collision!)
export BEADS_AGENT_NAME=fred-beads-macbook  # Same in fred/beads and fred/vc

# Good (unique)
export BEADS_AGENT_NAME=fred-beads-macbook   # In fred/beads
export BEADS_AGENT_NAME=fred-vc-macbook      # In fred/vc

The setup-agent-mail-workspace.sh script already handles this by including workspace name.

Issue: Server not accessible

Symptoms:

bd update bd-42 --status in_progress
# WARN Agent Mail unavailable, falling back to git-only mode

Fix:

# Check server health
curl http://127.0.0.1:8765/health
# If unreachable, restart server:
./scripts/stop-agent-mail-server.sh
./scripts/start-agent-mail-server.sh

Issue: Old reservations stuck

Symptoms: Agent crashed but reservation persists

Fix:

# Option 1: Release via API
curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-stuck

# Option 2: Restart server (clears all)
./scripts/stop-agent-mail-server.sh
./scripts/start-agent-mail-server.sh

Maintenance

Daily Operations

Start/stop server manually:

cd ~/src/fred/beads
./scripts/start-agent-mail-server.sh
./scripts/stop-agent-mail-server.sh

Check status:

./scripts/agent-mail-status.sh

View logs:

tail -f ~/agent-mail.log

Monitor Web UI:

open http://127.0.0.1:8765/mail

Upgrading beads

When you bump beads version in the future:

cd ~/src/fred/beads

# Bump version
./scripts/bump-version.sh 0.24.0 --commit
git push origin main
git push origin v0.24.0

# Wait for release, then upgrade all workspaces
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash

# Or rebuild locally and distribute
go build -o bd ./cmd/bd
# ... copy to other repos

Adding New Workspaces

To add a new workspace to Agent Mail coordination:

# Example: Adding ~/src/gina/beads
cd ~/src/gina/beads

# Run setup script
~/src/fred/beads/scripts/setup-agent-mail-workspace.sh .

# Allow direnv
direnv allow

# Verify configuration
echo $BEADS_PROJECT_ID
# Expected: beads.dev (or vc.dev/wyvern.dev)

# Test reservation
bd ready | head -1 | xargs -I {} bd update {} --status in_progress
# Should work immediately

Success Criteria

You've successfully deployed Agent Mail when:

1. ✅ Server running: curl http://127.0.0.1:8765/health returns healthy
2. ✅ All workspaces configured: 13 .envrc files created and allowed
3. ✅ Three channels active: beads.dev, vc.dev, wyvern.dev visible in Web UI
4. ✅ Coordination works: Reservation conflict test passes (Step 6a)
5. ✅ Isolation works: Different channels don't interfere (Step 6b)
6. ✅ Monitoring works: Status script shows all active projects
7. ✅ Auto-start works: Server survives reboot (if Step 8 completed)

Next Steps

After successful deployment:

1. Start using bd normally - Agent Mail coordination happens automatically
2. Monitor reservations via Web UI during concurrent work
3. File issues for any coordination bugs (rare with hash-based IDs)
4. Consider MCP integration for Claude Desktop (see docs/AGENT_MAIL_QUICKSTART.md)
5. Wait for cross-project messaging (planned in Agent Mail roadmap)

Reference

• Main Guide: AGENT_MAIL_MULTI_WORKSPACE_SETUP.md
• Quick Start: AGENT_MAIL_QUICKSTART.md
• Architecture: AGENT_MAIL.md
• ADR: adr/002-agent-mail-integration.md

Timeline Estimate

• Step 1 (Version bump): 5 minutes
• Step 2 (Start server): 2 minutes
• Step 3 (Configure 13 workspaces): 10 minutes
• Step 4 (Upgrade binaries): 5 minutes
• Step 5 (Document): 2 minutes
• Step 6 (Same-channel test): 5 minutes
• Step 7 (Channel isolation test): 5 minutes
• Step 8 (Monitor): 2 minutes
• Step 9 (Auto-start, optional): 5 minutes
• Step 10 (Verify checklist): 5 minutes

Total: ~46 minutes (or ~41 minutes if skipping auto-start)

You're ready to deploy! 🚀