kickinrad/setup

bridgey Setup

Interactive first-time configuration for the bridgey A2A communication daemon.

When to Use

Activate on first install or when no ~/.bridgey/bridgey.config.json exists. Also activate when the user explicitly asks to reconfigure bridgey.

Setup Procedure

1. Check Existing Config

Read ~/.bridgey/bridgey.config.json. If it exists, confirm with the user before overwriting.

2. Gather Configuration

Ask the user for each setting (provide sensible defaults):

| Setting | Default | Description | |---------|---------|-------------| | name | hostname or directory name | Unique agent name for this instance | | description | "Claude Code assistant" | Human-readable description (used in Agent Card) | | port | 8092 | HTTP port for the daemon | | bind | "localhost" | Network binding: localhost, lan, 0.0.0.0, or custom IP | | workspace | current working directory | Working directory for inbound requests | | max_turns | 10 | Max turns for claude -p on inbound requests |

Bind mode guide:

• "localhost" — only reachable from same machine (most secure, default)
• "lan" — binds to first non-localhost IPv4 (reachable on LAN)
• "0.0.0.0" — all interfaces (required for Docker containers, Tailscale)
• Custom IP — bind to a specific network interface

If the user picks "0.0.0.0" for bind, warn them:

"Binding to all interfaces exposes the daemon to the network. A bearer token protects it, but consider using localhost with Tailscale for secure remote access."

2b. Configure Trusted Networks (if non-localhost bind)

If the user chose a non-localhost bind, ask if they want to add trusted networks. Trusted CIDRs allow token-free access from known ranges:

| Network | CIDR | When to add | |---------|------|-------------| | Tailscale | 100.64.0.0/10 | Using Tailscale mesh or Tailscale SSH | | Docker bridge | 172.16.0.0/12 | Running in Docker containers | | Docker overlay | 10.0.0.0/8 | Docker Swarm or alternative bridge configs |

Add to config as "trusted_networks": ["100.64.0.0/10"] (or multiple CIDRs as needed).

3. Generate Security Token

Generate a bearer token automatically using crypto.randomBytes(16).toString('hex') prefixed with brg_. Display it to the user:

"Your bridgey token is brg_abc123.... Share this with agents that need to send you messages. Store it securely."

4. Write Config File

Write ~/.bridgey/bridgey.config.json:

{
  "name": "my-coder",
  "description": "General purpose Claude Code assistant",
  "port": 8092,
  "bind": "localhost",
  "token": "brg_a1b2c3d4...",
  "workspace": ".",
  "max_turns": 10,
  "agents": [],
  "trusted_networks": []
}

Note: trusted_networks is an empty array by default. Only populated if user chose non-localhost bind.

5. Start the Daemon

Run the daemon start command (if dist/daemon.js is missing, run npm run build from plugins/bridgey/ first):

node ${CLAUDE_PLUGIN_ROOT}/dist/daemon.js start \
  --config ~/.bridgey/bridgey.config.json

Verify it started by checking the health endpoint:

curl -s http://localhost:8092/health

6. Confirm Success

Show the user:

• Agent name and description
• Listening address and port
• Token (masked, e.g., brg_a1b2...)
• How to add remote agents: /bridgey:add-agent
• How to check status: /bridgey:status

Container / Headless Deployment Notes

If running in Docker or on a headless server:

• Bind must be 0.0.0.0 — localhost is unreachable from other containers
• Add Docker CIDRs to trusted_networks — 172.16.0.0/12 and 10.0.0.0/8
• Claude Code Max auth — OAuth tokens must be transferred from a logged-in machine. Copy ~/.claude/.credentials.json and mount it into the container.
• Inter-container references — use Docker DNS names (http://bridgey-mila:8093), not localhost

Notes

• Config file lives at ~/.bridgey/bridgey.config.json (survives plugin updates)
• The daemon is started automatically by the SessionStart hook on future sessions
• Local agents on the same machine discover each other automatically via ~/.bridgey/agents/
• Remote agents must be added manually with /bridgey:add-agent