diff --git a/Dockerfile b/Dockerfile
index 6a5fcd1f7..540a5af3e 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,4 +1,4 @@
-FROM golang:1.24-alpine AS builder
+FROM golang:1.25-alpine AS builder
 
 RUN apk add --no-cache git gcc musl-dev
 
diff --git a/PROPOSAL.md b/PROPOSAL.md
new file mode 100644
index 000000000..4621cd321
--- /dev/null
+++ b/PROPOSAL.md
@@ -0,0 +1,700 @@
+# Federated Relay Pool for Croc - Architecture and Implementation Notes
+
+**Status:** Implemented in v10.5.0  
+**Last Updated:** 2026-03-09 | **Revision:** 2.3 (Security-hardened)
+
+---
+
+## Executive Summary
+
+A lightweight relay **discovery + coordination** system that:
+
+- Allows community operators to register relays with the **Main Node** (pool)
+- Embeds relay IDs directly into share codes: `12ca-1571-yellow-apple`
+- Eliminates complex room coordination overhead
+- Maintains backward compatibility with existing TCP relay infrastructure
+- Keeps pool APIs minimal and stateless
+
+---
+
+## Architecture Overview
+
+### Components
+
+```
+┌─────────────────────────────────────────────────┐
+│         Main Node (Pool + Legacy TCP)        │
+│  - HTTP/REST API: /register, /heartbeat, /relays│
+│  - Relay Registry & Health Checks               │
+│  - TCP Relay (9009+) for legacy fallback        │
+└─────────────────────────────────────────────────┘
+         ↑                  ↓
+    (register/          (discover/
+     heartbeat)          cache)
+         ↑                  ↓
+  ┌──────────────────────────────────────┐
+  │  Community Relays (TCP servers)      │
+  │  - Relay#102: 203.0.113.5:9009       │
+  │  - Relay#103: 198.51.100.8:9009      │
+  │  - Relay#104: 192.0.2.15:9009        │
+  └──────────────────────────────────────┘
+         ↑
+    (heartbeat)
+         ↑
+  ┌──────────────────────────────────────┐
+  │   Croc Clients (Sender/Receiver)     │
+  │  - Cache: relay_id → IP:ports        │
+  │  - Generate: relay_id + secret       │
+  │  - Connect: Direct TCP to relay      │
+  └──────────────────────────────────────┘
+```
+
+### Data Flow
+
+**Sender (croc send file.txt):**
+
+```
+1. POST /relays → List of available {relay_id, ipv6, ipv4, ports, status, version} (**no password** — credentials are out-of-band)
+2. Cache relay registry locally
+3. Select relay (fastest, random, or preference)
+4. Generate code: "12ca-1571-yellow-apple"
+5. Connect TCP directly to relay (IPv6 first, fallback IPv4) using ports[0]
+6. Proceed with standard croc handshake
+7. On SIGINT/done: no explicit cleanup needed
+```
+
+**Receiver (croc 12ca-1571-yellow-apple):**
+
+```
+1. Parse relay_id = "12ca" from code
+2. Lookup relay_id in local cache → IPv6/IPv4 + ports
+3. If not cached: POST /relays (fallback lookup)
+4. Connect TCP directly to relay (IPv6 first, fallback IPv4) using ports[0]
+5. Proceed with standard croc handshake
+```
+
+**Community Relay Lifecycle:**
+
+```
+1. croc relay [--pool <pool_url>] [--ports 9009,9010,9011,9012,9013] node
+2. Detect public IP address (IPv6 preferred, IPv4 fallback)
+3. Calculate relay_id = SHA256(ip)[:2] as hex (4 chars)
+4. POST /register {ipv6, ipv4, ports, password}
+	→ Returns confirmation
+5. Loop every 10s: POST /heartbeat {relay_id}
+6. Main Node tracks: {relay_id → state, last_heartbeat}
+7. If heartbeat missing 30s+: mark Inactive
+8. On shutdown (SIGINT): cleanup heartbeat goroutine
+9. On restart: relay_id auto-regenerated from IP (no storage needed)
+
+If `--pool` is omitted, node mode uses the global default pool URL (http://croc.schollz.com:9000).
+If `--ports` is omitted, relay defaults are used (`9009,9010,9011,9012,9013`).
+```
+
+**Relay CLI Modes (proposed):**
+
+```
+1. croc relay                                    -> Legacy standalone relay (no pool)
+2. croc relay main                               -> Pool main node
+3. croc relay [--pool <url>] [--ports ...] node -> Pool community relay node
+4. if --pool is omitted, use internal default global pool constant
+5. if --ports is omitted, use relay defaults (9009-9013)
+```
+
+### Concrete CLI Examples
+
+**A) Backward-compatible standalone relay (no pool):**
+
+```bash
+# same behavior as today
+croc relay
+
+# custom standalone relay ports
+croc relay --ports 9009,9010,9011,9012,9013 --pass myrelaypass
+```
+
+**B) Private pool (default in pool modes):**
+
+```bash
+# 1) Start private pool main
+croc relay main --listen 10.0.0.10:9000
+
+# 2) Join first private pool node (uses default ports 9009-9013)
+croc relay --pool http://10.0.0.10:9000 --pass privatepass node
+
+# 3) Join second private pool node
+croc relay --pool http://10.0.0.10:9000 --ports 9109,9110,9111,9112,9113 --pass privatepass node
+
+# 4) Client uses private pool for relay discovery
+croc --pool http://10.0.0.10:9000 send file.txt
+```
+
+**C) Public pool:**
+
+```bash
+# 1) Start public pool main
+croc relay main --listen 0.0.0.0:9000
+
+# 2) Join global default public pool node #1
+# Note: --pool optional since http://croc.schollz.com:9000 is default
+croc relay --pass pass123 node
+
+# 3) Join specific non-default public pool node #2
+# Note: --pool required when NOT using default pool
+croc relay --pool http://pool.example.com:9000 --ports 9109,9110,9111,9112,9113 --pass pass123 node
+
+# 4) Client uses default global public pool
+# Note: no --pool flag needed, uses built-in default
+croc send file.txt
+
+# 5) Client targets a non-default public pool explicitly
+# Note: --pool required when NOT using default pool
+croc --pool http://pool.example.com:9000 send file.txt
+```
+
+**E) Client copy-paste quick commands:**
+
+```bash
+# default global pool (internal constant)
+croc send file.txt
+croc 12ca-1571-yellow-apple
+
+# non-default pool override (private or public)
+croc --pool http://10.0.0.10:9000 send file.txt
+croc --pool http://10.0.0.10:9000 12ca-1571-yellow-apple
+```
+
+**D) Client fallback remains unchanged:**
+
+```bash
+# If pool is unavailable or code has no relay prefix,
+# clients can still use classic direct relay addressing.
+croc --relay myrelay.example.com:9009 --pass myrelaypass send file.txt
+croc --relay myrelay.example.com:9009 --pass myrelaypass <code>
+```
+
+---
+
+## Implementation Overview
+
+### Phase 1: Core State Management
+
+Create a new pool coordination module that manages relay registry and state:
+
+**Relay State Tracking:**
+
+- Each relay has a unique 4-character hex ID (derived from IP hash)
+- Track both IPv6 (primary) and IPv4 (fallback) addresses
+- Monitor relay health through status (active/inactive)
+- Record last heartbeat timestamp
+- Store relay ports and optional password
+
+**Registry Requirements:**
+
+- Thread-safe concurrent access to relay data
+- Support upsert operations (register/update)
+- Query relays by ID
+- List active relays with randomization
+- Update heartbeat timestamps
+- Mark relays as inactive
+- Periodic cleanup of stale relays (30 second timeout)
+
+**Key Concepts:**
+
+- Relay ID must be deterministic based on IP address
+- IPv6 addresses take priority over IPv4
+- Relay IDs are deterministically regenerated from public IP on each registration
+- Inactive relays remain in registry but aren't distributed to clients
+
+---
+
+### Phase 2: Helper Utilities
+
+Provide support functions for relay pool operations:
+
+**IP Address Handling:**
+
+- Generate deterministic relay IDs from IP addresses using hash algorithm (SHA256, first 16 bits → 4 hex chars)
+- Relay ID is deterministic: same IP always produces same relay_id
+- **No storage needed on relay nodes**: relay_id recalculated from IP on each registration
+- Validate public IPv6 addresses (exclude loopback, private, link-local, multicast)
+- Validate public IPv4 addresses (exclude RFC 1918, CGNAT, loopback, link-local)
+- Prefer IPv6 over IPv4 when both available
+
+**Connectivity Testing:**
+
+- Check if relay is reachable via TCP connection
+- Try IPv6 first, fallback to IPv4
+- Use short timeout (1 second) to avoid blocking
+- Detect if local system supports IPv6
+
+**Code Parsing:**
+
+- Detect if code contains relay ID prefix (4-char hex)
+- Extract relay_id and secret from combined code format: `<relay_id>-<secret>`
+- Handle legacy codes without relay ID prefix
+- **Critical**: Room name must be derived from secret part AFTER relay_id, not from relay_id itself
+
+---
+
+### Phase 3: Pool HTTP API
+
+Implement a lightweight HTTP REST API for relay coordination:
+
+**Three Core Endpoints:**
+
+**1. POST /register** - Community relay registration
+
+- Accept relay connection details (IPv6/IPv4, ports, password)
+- Require at least one IP address (IPv6 or IPv4)
+- Require minimum 2 ports
+- Calculate deterministic relay_id from IP (SHA256 hash, first 2 bytes)
+- Store relay state as active with current timestamp
+- Return assigned relay_id for confirmation
+- Support upsert behavior (re-registration with same ID)
+
+**2. POST /heartbeat** - Keep relay alive
+
+- Accept relay ID
+- Update relay's last heartbeat timestamp
+- Mark relay as active
+- Return success confirmation
+- Return error if relay ID not found
+
+**3. POST /relays** - List active relays for clients
+
+- Return array of up to 50 active relays
+- Include relay ID, IPv6/IPv4 addresses, ports, status, node version (**password is never returned** — clients must obtain relay credentials out-of-band)
+- Randomize order to distribute load
+- Only include relays marked as active
+
+**Background Tasks:**
+
+- Run periodic cleanup every 30 seconds (equal to heartbeat timeout, to minimise stale-relay exposure)
+- Mark relays as inactive if no heartbeat for 30+ seconds
+- Cleanup also runs eagerly before each /relays response
+- Keep inactive relays in registry for potential recovery
+
+**Server Configuration:**
+
+- Listen on configurable address (default: 0.0.0.0:9000)
+- Use HTTP web framework for routing
+- Log all registration and heartbeat events
+
+---
+
+### Phase 4: Relay Command Enhancement
+
+Extend the existing relay command to support pool federation:
+
+**Three Relay Modes:**
+
+**Mode 1: croc relay** (Legacy Standalone)
+
+- Maintain existing behavior unchanged
+- Start TCP relay without any pool interaction
+- Fully backward compatible
+- No pool coordination
+
+**Mode 2: croc relay main** (Pool Main Node)
+
+- Start HTTP pool API server
+- Manage relay registry and health monitoring
+- Provide relay discovery for clients
+- Listen on configurable address (--listen flag)
+- Optional: Also run legacy TCP relay for fallback
+
+**Mode 3: croc relay [flags] node** (Community Relay Node)
+
+- Start standard TCP relay on specified ports
+- Register with pool on startup
+- Send periodic heartbeats every 10 seconds
+- Use server-assigned deterministic relay ID derived from public IP
+- Auto-reconnect to pool on network failures
+
+**Community Node Workflow:**
+
+1. **Configuration Resolution:**
+   - Pool URL: CLI flag → environment variable → default
+   - Ports: CLI flag → defaults (9009-9013)
+   - Default pool: http://croc.schollz.com:9000
+   - Note: `--pool` optional when using default
+
+2. **IP Address Detection:**
+   - Detect public IPv6 address (preferred)
+   - Detect public IPv4 address (fallback)
+   - At least one public IP required
+   - Calculate relay_id from IP: `SHA256(ip)[:2]` as hex
+
+3. **Startup Sequence:**
+   - Detect public IP and build register payload
+   - Register with pool to obtain relay_id
+   - Begin heartbeat loop
+   - Start TCP relay listeners on all ports
+
+4. **Registration + Heartbeat Loop:**
+   - POST to /register with connection details
+   - Receive relay_id from main node
+   - POST to /heartbeat every 10 seconds
+   - Log failures but continue retrying
+   - Don't crash on temporary network issues
+
+5. **Graceful Shutdown:**
+   - Stop heartbeat loop on SIGINT
+   - Close TCP listeners
+   - No cleanup needed (relay_id recalculated on next start)
+
+---
+
+### Phase 5: Client Integration
+
+Enhance croc clients to support federated relay discovery:
+
+**Client-Side Relay Cache:**
+
+- Maintain local cache mapping relay IDs to connection info
+- Cache includes: IPv6/IPv4 addresses, ports, node version (passwords not cached from pool; known out-of-band)
+- Allow pool URL override via config
+
+**Relay Discovery Workflow:**
+
+- Query pool: POST to /relays endpoint
+- Receive list of active relays
+- Store in local cache for session
+- Cache remains valid until client restart
+- On cache miss, re-query pool
+
+**Sender Workflow (croc send file.txt):**
+
+1. **Determine Relay Mode:**
+   - If `--relay` explicitly set: use direct relay (legacy mode, skip pool)
+   - If `--pool` explicitly set: use that pool URL
+   - If `CROC_POOL_URL` env var set: use that pool
+   - Else: try default pool (http://croc.schollz.com:9000)
+   - Note: `--pool` flag optional when using default pool
+
+2. **Query Pool for Relays (if pool mode):**
+   - POST to /relays endpoint
+   - Cache all returned relays locally for this session
+   - If pool unreachable: fallback to default relay (legacy mode)
+
+3. **Select Best Relay:**
+   - Test connectivity to cached relays (1 second timeout)
+   - Build list of reachable relays
+   - Select relay (random, first, or lowest latency)
+   - If all fail, fallback to default relay
+
+4. **Generate Federated Code:**
+   - Call `utils.GetRandomName(relay_id)` with selected relay's ID
+   - Format: `<relay_id>-<pin>-<words>`
+   - Example: `12ca-1571-yellow-apple`
+   - If no pool relay selected, use legacy format: `utils.GetRandomName("")`
+   - **Important**: Code generation happens AFTER relay selection
+
+5. **Connect to Selected Relay:**
+   - Use IPv6 address if available
+   - Fallback to IPv4 if IPv6 unavailable
+   - Use relay's password from cache
+
+**Receiver Workflow (croc 12ca-1571-yellow-apple):**
+
+1. **Parse Transfer Code:**
+   - Check if first segment (before first dash) is 4-char hex pattern
+   - If yes: `relay_id = "12ca"`, `secret = "1571-yellow-apple"`
+   - If no: treat entire code as secret (legacy mode)
+
+2. **Generate Room Name:**
+   - **Critical**: Room name derived from secret part, NOT relay_id
+   - `roomName = SHA256(secret[:4] + hashExtra)`
+   - In example: `roomName = SHA256("7123" + "croc")`
+   - This ensures unique rooms per transfer, not per relay
+
+3. **Lookup Relay Information:**
+   - If relay_id found, check local cache
+   - If not in cache, query pool: POST /relays, find matching relay_id
+   - Pool URL resolved from: `--pool` flag → `CROC_POOL_URL` env → default
+   - If using default pool, `--pool` flag not required
+   - If relay not found anywhere, fallback to default relay
+
+4. **Connect to Relay:**
+   - Use cached relay connection info (IP, ports, password)
+   - Try IPv6 first, fallback to IPv4
+   - Apply relay password from cache
+   - Use room name derived from secret (not relay_id)
+   - Log connection details
+
+**Fallback Strategy:**
+
+- If pool unreachable: use hardcoded default relay
+- If relay_id not found: use default relay
+- If relay connection fails: timeout and report error
+- Legacy codes (no relay_id) always work via default relay
+
+---
+
+### Phase 6: Configuration & Integration
+
+**Required Dependencies:**
+
+- HTTP web framework for REST API implementation
+- Thread-safe concurrent map for relay registry
+- Standard libraries for networking, JSON, hashing
+
+**Configuration Constants:**
+
+- Default pool URL: http://croc.schollz.com:9000 (built-in constant)
+- Default relay address: croc.schollz.com:9009 (legacy fallback)
+- Relay status values: "active", "inactive"
+- Heartbeat timeout: 30 seconds
+- Heartbeat interval: 10 seconds
+- Relay ID length: 4 hex characters (2 bytes from SHA256)
+- Default ports: 9009,9010,9011,9012,9013
+
+**Environment Variables:**
+
+_Pool Server:_
+
+- CROC_POOL_LISTEN - API listen address (e.g., "0.0.0.0:9000")
+
+_Relay Nodes:_
+
+- CROC_POOL_URL - Pool URL for registration (e.g., "http://croc.schollz.com:9000")
+- CROC_RELAY_PORTS - Port list override (e.g., "9009,9010,9011,9012,9013")
+
+_Clients:_
+
+- CROC_POOL_URL - Pool URL for relay discovery (same variable as relay nodes)
+- CROC_RELAY - Direct relay address, disables pool mode (legacy, still supported)
+- CROC_RELAY6 - Direct IPv6 relay address (legacy, still supported)
+
+**Note:** Default pool URL is built-in constant, so CROC_POOL_URL only needed for non-default pools
+
+**Configuration Priority:**
+
+1. CLI flags (highest)
+2. Environment variables
+3. Default constants (lowest)
+
+**Relay ID Generation (No Storage Needed):**
+
+- Relay ID is deterministically calculated from relay's public IP address
+- Hash algorithm: `relay_id = hex(SHA256(ip_address)[:2])` → 4 hex chars
+- Same IP always produces same relay_id (idempotent)
+- **No `.relay_id` file needed on relay nodes** - just recalculate from IP
+- On restart, relay detects its public IP and regenerates same relay_id
+- This ensures transfer codes remain valid after relay restarts
+- Pool handles re-registration (upsert behavior) automatically
+
+---
+
+## Simplified HTTP Model
+
+1. Pool exposes only three endpoints: `/register`, `/heartbeat`, `/relays`.
+2. No token auth, no signature layer, and no TTL response fields.
+3. Relay state is binary: `active` or `inactive`.
+4. Heartbeats only refresh `last_heartbeat` and keep status `active`.
+5. Missing heartbeat beyond timeout marks relay `inactive`.
+
+---
+
+## End-to-End Walkthrough
+
+### Scenario: Federated Transfer
+
+**Setup:**
+
+- Main Node Pool: `croc.schollz.com:9000` (HTTP API) + `:9009` (legacy TCP fallback)
+- Community Relay#102: `203.0.113.5` (owns IP, ports 9009-9013)
+- Community Relay#103: `198.51.100.8` (owns IP, ports 9009-9013)
+
+**Execution:**
+
+1. **Community Relay boots (first time):**
+
+   ```bash
+   $ croc relay --pool http://croc.schollz.com:9000 --pass relay_pass node
+
+   [INFO] Starting TCP relay on 203.0.113.5:9009...
+   [INFO] Registering with pool...
+   [INFO] Detected public IP: 203.0.113.5
+   [INFO] Assigned relay_id: 12ca
+   [INFO] Registered as relay#12ca
+   [INFO] Sending heartbeats every 10s
+   ```
+
+**Pool sees:**
+
+- Relay assigned ID: `12ca` (deterministic from IP hash)
+- Status: `active`
+
+2. **Community Relay restarts (crash/maintenance):**
+
+   ```bash
+   $ croc relay --pool http://croc.schollz.com:9000 node ...
+
+   [INFO] Starting TCP relay on 203.0.113.5:9009...
+   [INFO] Detected public IP: 203.0.113.5
+   [INFO] Assigned relay_id from pool: 12ca
+   [INFO] Re-registering with pool...
+   [INFO] Relay#12ca re-activated (same ID as before)
+   ```
+
+   **Key insight:** Relay_id deterministically derived from IP → no storage needed, existing codes always work!
+
+3. **Sender initiates transfer:**
+
+   ```bash
+   $ croc send largefile.bin
+
+   [INFO] Querying pool for available relays...
+   [INFO] Got: relay#12ca (203.0.113.5), relay#44bd (198.51.100.8)
+   [INFO] Cached both locally
+   [INFO] Latency check: 12ca→45ms, 44bd→120ms
+   [INFO] Selected relay#12ca
+   [INFO] Generated code: 12ca-1571-yellow-apple
+
+   Code is: 12ca-1571-yellow-apple
+   On the other computer run:
+      croc 12ca-1571-yellow-apple
+   ```
+
+4. **Receiver joins (different computer, later):**
+
+   ```bash
+   $ croc 12ca-1571-yellow-apple
+
+   [INFO] Parsed code: relay_id=12ca, secret=1571-yellow-apple
+   [INFO] Checking relay cache...
+   [INFO] Not in cache, querying pool... (if no previous transfer)
+   [INFO] Found relay#12ca → 203.0.113.5:9009
+   [INFO] Connecting to 203.0.113.5:9009...
+   [INFO] Connected! Waiting for sender...
+   ```
+
+5. **Transfer completes:**
+
+   ```
+   largefile.bin (125 MB) 100% |████████████| [5s, 25MB/s]
+   Received
+   ```
+
+6. **Cleanup:**
+   - Sender/Receiver close TCP connections
+   - Room auto-expires on relay (no explicit cleanup needed)
+   - Community Relay continues serving, sends next heartbeat
+   - Relay_id remains stable (deterministic from IP) for next boot
+
+---
+
+## Implementation Checklist
+
+**Phase 1: Helper Utilities** (Foundation)
+
+- [x] Create `src/pool/utils.go`
+- [x] Implement relay ID generation from IP hash (deterministic)
+- [x] Implement public IP validation (IPv4/IPv6)
+- [x] Implement code parsing (detect relay_id prefix)
+- [x] Modify `src/utils/utils.go::GetRandomName(relay_id string)` to accept optional relay_id
+- [x] Add tests for code generation with/without relay_id
+
+**Phase 2: Core State Management** (Pool Registry)
+
+- [x] Create `src/pool/registry.go`
+- [x] Implement thread-safe relay registry (concurrent map)
+- [x] Add relay state tracking (active/inactive)
+- [x] Implement upsert operations (register/update)
+- [x] Implement query by relay_id
+- [x] Implement list active relays with randomization
+- [x] Add periodic cleanup mechanism (30s timeout)
+
+**Phase 3: Pool HTTP API** (Server)
+
+- [x] Create `src/pool/pool.go`
+- [x] Implement POST /register endpoint
+- [x] Implement POST /heartbeat endpoint
+- [x] Implement POST /relays endpoint
+- [x] Add background cleanup goroutine
+- [x] Add request validation and error handling
+- [x] Add logging for all operations
+
+**Phase 4: Relay Command Enhancement** (Node Mode)
+
+- [x] Modify `src/cli/cli.go::relay()` function
+- [x] Add subcommand detection (main/node)
+- [x] Implement "croc relay main" (pool server mode)
+- [x] Implement "croc relay [flags] node" (community relay mode)
+- [x] Add flags: --pool, --public, --listen
+- [x] Implement registration/heartbeat loop in node mode
+- [x] Add public IP detection for relay nodes
+- [x] Test pool server startup and relay registration
+
+**Phase 5: Client Integration** (Send/Receive)
+
+- [x] Create `src/pool/client.go` for pool queries
+- [x] Add relay cache to client struct
+- [x] Implement relay mode detection logic
+- [x] Modify `src/cli/cli.go::send()` to query pool before code generation
+- [x] Modify sender to call `GetRandomName()` with relay_id after selection
+- [x] Modify `src/croc/croc.go::New()` to parse relay_id from codes
+- [x] Fix room name generation to use secret part (not relay_id)
+- [x] Modify receiver to query pool for relay lookup
+- [x] Add IPv6-first connection logic
+- [x] Implement fallback strategies (pool → default relay)
+
+**Phase 6: Testing & Validation**
+
+- [x] Test pool server startup and API endpoints
+- [x] Test community relay registration (first time)
+- [x] Test relay restart with same IP (relay_id regeneration)
+- [x] Test heartbeat mechanism and timeout
+- [x] Test sender: pool query → relay selection → code generation flow
+- [x] Test receiver: code parsing → pool lookup → connection
+- [x] Test relay_id determinism (same IP = same ID)
+- [x] Test room name generation (uniqueness per transfer)
+- [x] Test IPv6/IPv4 fallback
+- [x] Test pool unavailability fallback to default relay
+- [x] Test legacy codes (no relay_id prefix)
+- [x] Test backward compatibility with old clients
+
+**Phase 7: Documentation & Deployment**
+
+- [x] Update README with pool architecture overview
+- [x] Document new CLI commands (relay main, relay node)
+- [x] Document all environment variables (CROC_POOL_URL, etc.)
+- [x] Create usage examples for private and public pools
+- [ ] Write migration guide for existing relay operators
+- [x] Document code format change (relay_id prefix)
+- [ ] Add troubleshooting guide (pool connection failures, etc.)
+
+---
+
+## Backward Compatibility
+
+✅ **Fully maintained:**
+
+- Legacy codes (no relay ID prefix) work as before
+- Default relay `croc.schollz.com:9009` still available
+- Existing standalone relay workflow remains: `croc relay`
+- Existing `--relay` flag respected
+- Zero changes to core TCP relay protocol
+- Versionless pool API (no version header required)
+
+✅ **Graceful degradation:**
+
+- If pool unreachable: use hardcoded relay
+- If selected relay fails: timeout & fallback to default
+- If relay_id not found: use default relay
+- If main node reboots: relay_id re-registers from deterministic IP hash, codes remain valid
+
+✅ **No BREAKING changes:**
+
+- Existing clients unaffected
+- Relay_id embedding is optional (codes work with or without prefix)
+- Pool API backward compatible (no versioning discipline)
+
+---
+
+## References
+
+- **croc GitHub:** https://github.com/schollz/croc
+- **Go net/http Docs:** https://pkg.go.dev/net/http
diff --git a/README.md b/README.md
index 9573e58a5..1d865a217 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@
 
 ## About
 
-`croc` is a tool that allows any two computers to simply and securely transfer files and folders. AFAIK, *croc* is the only CLI file-transfer tool that does **all** of the following:
+`croc` is a tool that allows any two computers to simply and securely transfer files and folders. AFAIK, _croc_ is the only CLI file-transfer tool that does **all** of the following:
 
 - Allows **any two computers** to transfer data (using a relay)
 - Provides **end-to-end encryption** (using PAKE)
@@ -146,7 +146,7 @@ Or install into a particular environment with [`conda`](https://docs.conda.io/pr
 conda install --channel conda-forge croc
 ```
 
-### On Linux, macOS via Docker 
+### On Linux, macOS via Docker
 
 Add the following one-liner function to your ~/.profile (works with any POSIX-compliant shell):
 
@@ -328,6 +328,74 @@ To send files using your relay:
 croc --relay "myrelay.example.com:9009" send [filename]
 ```
 
+#### Federated Relay Pool (Main + Community Nodes)
+
+You can run a pool-based relay network where:
+
+- a main node provides relay discovery APIs,
+- community relay nodes register themselves,
+- senders and receivers automatically discover relays from the pool.
+
+Pool endpoints:
+
+- `POST /register`
+- `POST /heartbeat`
+- `POST /relays`
+
+There are two common deployment types.
+
+##### Type 1: Public Pool (Built-in Defaults)
+
+Built-in defaults:
+
+- Pool URL: `http://croc.schollz.com:9000`
+- Relay password default: `pass123`
+
+Use these commands:
+
+```bash
+# Community relay node joins default public pool
+# Note: for relay node mode, place flags before the trailing "node" argument
+croc relay node
+
+# Sender (default pool is used automatically)
+croc send log.txt
+
+# Receiver (default pool is used automatically)
+croc RELAYID-PIN-WORD-WORD-WORD
+```
+
+##### Type 2: Custom Pool
+
+Use these commands:
+
+```bash
+# 1) Start main node (pool API)
+croc relay main --listen 0.0.0.0:9000
+
+# 2) Start a community relay node and register to the pool
+# Note: for relay node mode, place flags before the trailing "node" argument
+croc relay --pool http://POOL_IP:9000 --pass YOUR_POOL_PASS --ports 9009,9010,9011,9012,9013 node
+
+# 3) Sender uses pool discovery
+croc --pool http://POOL_IP:9000 send log.txt
+
+# 4) Receiver uses the transfer code from sender
+croc --pool http://POOL_IP:9000 RELAYID-PIN-WORD-WORD-WORD
+```
+
+Example transfer code format:
+
+```text
+12ca-1571-friday-brown-fluid
+```
+
+Notes:
+
+- If `--pool` is omitted, croc uses the built-in default pool URL.
+- If pool discovery fails, croc falls back to legacy relay behavior.
+- Legacy direct relay mode with `--relay` continues to work unchanged.
+
 #### Self-host Relay with Docker
 
 You can also run a relay with Docker:
diff --git a/src/cli/cli.go b/src/cli/cli.go
index c1061b990..7e245824d 100644
--- a/src/cli/cli.go
+++ b/src/cli/cli.go
@@ -1,16 +1,20 @@
 package cli
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
+	"net"
 	"os"
+	"os/signal"
 	"path"
 	"path/filepath"
 	"runtime"
 	"strconv"
 	"strings"
+	"syscall"
 	"time"
 
 	"github.com/chzyer/readline"
@@ -19,6 +23,7 @@ import (
 	"github.com/schollz/croc/v10/src/croc"
 	"github.com/schollz/croc/v10/src/mnemonicode"
 	"github.com/schollz/croc/v10/src/models"
+	"github.com/schollz/croc/v10/src/pool"
 	"github.com/schollz/croc/v10/src/tcp"
 	"github.com/schollz/croc/v10/src/utils"
 	log "github.com/schollz/logger"
@@ -36,7 +41,7 @@ func Run() (err error) {
 	app := cli.NewApp()
 	app.Name = "croc"
 	if Version == "" {
-		Version = "v10.4.1"
+		Version = "v10.5.0"
 	}
 	app.Version = Version
 	app.Compiled = time.Now()
@@ -94,6 +99,8 @@ func Run() (err error) {
 			Flags: []cli.Flag{
 				&cli.StringFlag{Name: "host", Usage: "host of the relay"},
 				&cli.StringFlag{Name: "ports", Value: "9009,9010,9011,9012,9013", Usage: "ports of the relay"},
+				&cli.StringFlag{Name: "listen", Value: models.DEFAULT_POOL_LISTEN, Usage: "listen address for relay main pool API", EnvVars: []string{"CROC_POOL_LISTEN"}},
+				&cli.StringFlag{Name: "pool", Value: models.DEFAULT_POOL_URL, Usage: "pool URL for relay node registration", EnvVars: []string{"CROC_POOL_URL"}},
 				&cli.IntFlag{Name: "port", Value: 9009, Usage: "base port for the relay"},
 				&cli.IntFlag{Name: "transfers", Value: 5, Usage: "number of ports to use for relay"},
 			},
@@ -133,6 +140,7 @@ func Run() (err error) {
 		&cli.StringFlag{Name: "ip", Value: "", Usage: "set sender ip if known e.g. 10.0.0.1:9009, [::1]:9009"},
 		&cli.StringFlag{Name: "relay", Value: models.DEFAULT_RELAY, Usage: "address of the relay", EnvVars: []string{"CROC_RELAY"}},
 		&cli.StringFlag{Name: "relay6", Value: models.DEFAULT_RELAY6, Usage: "ipv6 address of the relay", EnvVars: []string{"CROC_RELAY6"}},
+		&cli.StringFlag{Name: "pool", Value: models.DEFAULT_POOL_URL, Usage: "pool URL for relay discovery", EnvVars: []string{"CROC_POOL_URL"}},
 		&cli.StringFlag{Name: "out", Value: ".", Usage: "specify an output folder to receive the file"},
 		&cli.StringFlag{Name: "pass", Value: models.DEFAULT_PASSPHRASE, Usage: "password for the relay", EnvVars: []string{"CROC_PASS"}},
 		&cli.StringFlag{Name: "socks5", Value: "", Usage: "add a socks5 proxy", EnvVars: []string{"SOCKS5_PROXY"}},
@@ -234,7 +242,7 @@ func setDebugLevel(c *cli.Context) {
 		log.SetLevel("debug")
 		log.Debug("debug mode on")
 		// print the public IP address
-		ip, err := utils.PublicIP()
+		ip, err := utils.PublicIPv4()
 		if err == nil {
 			log.Debugf("public IP address: %s", ip)
 		} else {
@@ -309,33 +317,33 @@ func send(c *cli.Context) (err error) {
 	}
 
 	crocOptions := croc.Options{
-		SharedSecret:     c.String("code"),
-		IsSender:         true,
-		Debug:            c.Bool("debug"),
-		NoPrompt:         c.Bool("yes"),
-		RelayAddress:     c.String("relay"),
-		RelayAddress6:    c.String("relay6"),
-		Stdout:           c.Bool("stdout"),
-		DisableLocal:     c.Bool("no-local"),
-		OnlyLocal:        c.Bool("local"),
-		IgnoreStdin:      c.Bool("ignore-stdin"),
-		RelayPorts:       ports,
-		Ask:              c.Bool("ask"),
-		NoMultiplexing:   c.Bool("no-multi"),
-		RelayPassword:    determinePass(c),
-		SendingText:      c.String("text") != "",
-		NoCompress:       c.Bool("no-compress"),
-		Overwrite:        c.Bool("overwrite"),
-		Curve:            c.String("curve"),
-		HashAlgorithm:    c.String("hash"),
-		ThrottleUpload:   c.String("throttleUpload"),
-		ZipFolder:        c.Bool("zip"),
-		GitIgnore:        c.Bool("git"),
-		ShowQrCode:       c.Bool("qrcode"),
-		MulticastAddress: c.String("multicast"),
-		Exclude:          excludeStrings,
-		Quiet:            c.Bool("quiet"),
-		DisableClipboard: c.Bool("disable-clipboard"),
+		SharedSecret:      c.String("code"),
+		IsSender:          true,
+		Debug:             c.Bool("debug"),
+		NoPrompt:          c.Bool("yes"),
+		RelayAddress:      c.String("relay"),
+		RelayAddress6:     c.String("relay6"),
+		Stdout:            c.Bool("stdout"),
+		DisableLocal:      c.Bool("no-local"),
+		OnlyLocal:         c.Bool("local"),
+		IgnoreStdin:       c.Bool("ignore-stdin"),
+		RelayPorts:        ports,
+		Ask:               c.Bool("ask"),
+		NoMultiplexing:    c.Bool("no-multi"),
+		RelayPassword:     determinePass(c),
+		SendingText:       c.String("text") != "",
+		NoCompress:        c.Bool("no-compress"),
+		Overwrite:         c.Bool("overwrite"),
+		Curve:             c.String("curve"),
+		HashAlgorithm:     c.String("hash"),
+		ThrottleUpload:    c.String("throttleUpload"),
+		ZipFolder:         c.Bool("zip"),
+		GitIgnore:         c.Bool("git"),
+		ShowQrCode:        c.Bool("qrcode"),
+		MulticastAddress:  c.String("multicast"),
+		Exclude:           excludeStrings,
+		Quiet:             c.Bool("quiet"),
+		DisableClipboard:  c.Bool("disable-clipboard"),
 		ExtendedClipboard: c.Bool("extended-clipboard"),
 	}
 	if crocOptions.RelayAddress != models.DEFAULT_RELAY {
@@ -450,9 +458,18 @@ Or you can go back to the classic croc behavior by enabling classic mode:
 		}
 	}
 
+	selectedRelayID := ""
+	if len(crocOptions.SharedSecret) == 0 && shouldUsePoolDiscovery(c) {
+		selectedRelayID = applyPoolRelayForSender(c, &crocOptions)
+	}
+
 	if len(crocOptions.SharedSecret) == 0 {
 		// generate code phrase
-		crocOptions.SharedSecret = utils.GetRandomName()
+		if selectedRelayID != "" {
+			crocOptions.SharedSecret = utils.GetRandomName(selectedRelayID)
+		} else {
+			crocOptions.SharedSecret = utils.GetRandomName()
+		}
 	}
 	minimalFileInfos, emptyFoldersToTransfer, totalNumberFolders, err := croc.GetFilesInfo(fnames, crocOptions.ZipFolder, crocOptions.GitIgnore, crocOptions.Exclude)
 	if err != nil {
@@ -612,23 +629,23 @@ func receive(c *cli.Context) (err error) {
 	comm.Socks5Proxy = c.String("socks5")
 	comm.HttpProxy = c.String("connect")
 	crocOptions := croc.Options{
-		SharedSecret:     c.String("code"),
-		IsSender:         false,
-		Debug:            c.Bool("debug"),
-		NoPrompt:         c.Bool("yes"),
-		RelayAddress:     c.String("relay"),
-		RelayAddress6:    c.String("relay6"),
-		Stdout:           c.Bool("stdout"),
-		Ask:              c.Bool("ask"),
-		RelayPassword:    determinePass(c),
-		OnlyLocal:        c.Bool("local"),
-		IP:               c.String("ip"),
-		Overwrite:        c.Bool("overwrite"),
-		Curve:            c.String("curve"),
-		TestFlag:         c.Bool("testing"),
-		MulticastAddress: c.String("multicast"),
-		Quiet:            c.Bool("quiet"),
-		DisableClipboard: c.Bool("disable-clipboard"),
+		SharedSecret:      c.String("code"),
+		IsSender:          false,
+		Debug:             c.Bool("debug"),
+		NoPrompt:          c.Bool("yes"),
+		RelayAddress:      c.String("relay"),
+		RelayAddress6:     c.String("relay6"),
+		Stdout:            c.Bool("stdout"),
+		Ask:               c.Bool("ask"),
+		RelayPassword:     determinePass(c),
+		OnlyLocal:         c.Bool("local"),
+		IP:                c.String("ip"),
+		Overwrite:         c.Bool("overwrite"),
+		Curve:             c.String("curve"),
+		TestFlag:          c.Bool("testing"),
+		MulticastAddress:  c.String("multicast"),
+		Quiet:             c.Bool("quiet"),
+		DisableClipboard:  c.Bool("disable-clipboard"),
 		ExtendedClipboard: c.Bool("extended-clipboard"),
 	}
 	if crocOptions.RelayAddress != models.DEFAULT_RELAY {
@@ -740,6 +757,8 @@ Or you can go back to the classic croc behavior by enabling classic mode:
 		}
 	}
 
+	applyPoolRelayForReceiver(c, &crocOptions)
+
 	cr, err := croc.New(crocOptions)
 	if err != nil {
 		return
@@ -782,11 +801,115 @@ func relay(c *cli.Context) (err error) {
 	if c.Bool("debug") {
 		debugString = "debug"
 	}
+
+	mode := strings.ToLower(strings.TrimSpace(c.Args().First()))
+	if mode == "main" {
+		return relayMain(c, debugString)
+	}
+	if mode == "node" {
+		return relayNode(c, debugString)
+	}
+	return relayLegacy(c, debugString)
+}
+
+func relayMain(c *cli.Context, debugString string) error {
+	listenAddr := c.String("listen")
+	if strings.TrimSpace(listenAddr) == "" {
+		listenAddr = models.DEFAULT_POOL_LISTEN
+	}
+
+	server := pool.NewServer(listenAddr)
+	server.HeartbeatTimeout = models.POOL_HEARTBEAT_TIMEOUT
+	server.CleanupInterval = models.POOL_CLEANUP_INTERVAL
+
 	host := c.String("host")
-	var ports []string
+	ports, err := parseRelayPorts(c)
+	if err != nil {
+		return err
+	}
+	pass := determinePass(c)
+	go func() {
+		if err := runRelayServers(debugString, host, ports, pass); err != nil {
+			log.Errorf("relay TCP servers error: %v", err)
+		}
+	}()
 
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	return server.Start(ctx)
+}
+
+func relayNode(c *cli.Context, debugString string) error {
+	host := c.String("host")
+	ports, err := parseRelayPorts(c)
+	if err != nil {
+		return err
+	}
+
+	registerReq := pool.RegisterRequest{Ports: ports, Password: determinePass(c)}
+	if ipv4, err4 := utils.PublicIPv4(); err4 == nil {
+		if pool.IsPublicIPv4(strings.TrimSpace(ipv4)) {
+			registerReq.IPv4 = strings.TrimSpace(ipv4)
+		}
+	}
+	if ipv6, err6 := utils.PublicIPv6(); err6 == nil {
+		if pool.IsPublicIPv6(strings.TrimSpace(ipv6)) {
+			registerReq.IPv6 = strings.TrimSpace(ipv6)
+		}
+	}
+	if registerReq.IPv4 == "" && registerReq.IPv6 == "" {
+		return fmt.Errorf("could not detect a globally routable public IP address")
+	}
+
+	poolURL := strings.TrimSpace(c.String("pool"))
+	if poolURL == "" {
+		poolURL = models.DEFAULT_POOL_URL
+	}
+	poolClient := pool.NewClient(poolURL)
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	registerResp, err := poolClient.Register(ctx, registerReq)
+	cancel()
+	if err != nil {
+		return fmt.Errorf("could not register relay with pool: %w", err)
+	}
+	log.Infof("registered relay node with relay_id=%s on pool=%s", registerResp.RelayID, poolURL)
+
+	go func() {
+		ticker := time.NewTicker(models.POOL_HEARTBEAT_INTERVAL)
+		defer ticker.Stop()
+		for range ticker.C {
+			hbCtx, hbCancel := context.WithTimeout(context.Background(), 3*time.Second)
+			hbErr := poolClient.Heartbeat(hbCtx, registerResp.RelayID)
+			hbCancel()
+			if hbErr != nil {
+				log.Errorf("heartbeat failed for relay_id=%s: %v", registerResp.RelayID, hbErr)
+				continue
+			}
+			log.Debugf("heartbeat sent for relay_id=%s", registerResp.RelayID)
+		}
+	}()
+
+	return runRelayServers(debugString, host, ports, determinePass(c))
+}
+
+func relayLegacy(c *cli.Context, debugString string) error {
+	host := c.String("host")
+	ports, err := parseRelayPorts(c)
+	if err != nil {
+		return err
+	}
+	return runRelayServers(debugString, host, ports, determinePass(c))
+}
+
+func parseRelayPorts(c *cli.Context) ([]string, error) {
+	var ports []string
 	if c.IsSet("ports") {
-		ports = strings.Split(c.String("ports"), ",")
+		for _, p := range strings.Split(c.String("ports"), ",") {
+			p = strings.TrimSpace(p)
+			if p != "" {
+				ports = append(ports, p)
+			}
+		}
 	} else {
 		portString := c.Int("port")
 		if portString == 0 {
@@ -802,20 +925,97 @@ func relay(c *cli.Context) (err error) {
 		}
 	}
 	if len(ports) < 2 {
-		return fmt.Errorf("relay requires at least two ports; specify --ports with two or more ports or set --transfers to 2+")
+		return nil, fmt.Errorf("relay requires at least two ports; specify --ports with two or more ports or set --transfers to 2+")
 	}
+	return ports, nil
+}
 
-	tcpPorts := strings.Join(ports[1:], ",")
+func startRelayServers(debugString, host string, ports []string, pass string) {
 	for i, port := range ports {
 		if i == 0 {
 			continue
 		}
 		go func(portStr string) {
-			err := tcp.Run(debugString, host, portStr, determinePass(c))
+			err := tcp.Run(debugString, host, portStr, pass)
 			if err != nil {
 				panic(err)
 			}
 		}(port)
 	}
-	return tcp.Run(debugString, host, ports[0], determinePass(c), tcpPorts)
+}
+
+func runRelayServers(debugString, host string, ports []string, pass string) error {
+	startRelayServers(debugString, host, ports, pass)
+	tcpPorts := strings.Join(ports[1:], ",")
+	return tcp.Run(debugString, host, ports[0], pass, tcpPorts)
+}
+
+func shouldUsePoolDiscovery(c *cli.Context) bool {
+	// Explicit direct-relay configuration disables pool discovery.
+	if c.IsSet("relay") || c.IsSet("relay6") {
+		return false
+	}
+	return true
+}
+
+func applyPoolRelayForSender(c *cli.Context, crocOptions *croc.Options) string {
+	poolURL := strings.TrimSpace(c.String("pool"))
+	poolClient := pool.NewClient(poolURL)
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	relays, err := poolClient.FetchRelays(ctx)
+	cancel()
+	if err != nil {
+		log.Debugf("pool relay fetch failed, using legacy relay fallback: %v", err)
+		return ""
+	}
+	relay, ok := poolClient.ChooseRandomReachableRelay(relays)
+	if !ok {
+		log.Debug("no reachable pool relays found, using legacy relay fallback")
+		return ""
+	}
+	applyRelayToOptions(crocOptions, relay)
+	log.Infof("selected relay_id=%s from pool for sender", relay.RelayID)
+	return relay.RelayID
+}
+
+func applyPoolRelayForReceiver(c *cli.Context, crocOptions *croc.Options) {
+	relayID, _ := pool.ParseTransferCode(crocOptions.SharedSecret)
+	if relayID == "" {
+		return
+	}
+	if !shouldUsePoolDiscovery(c) {
+		return
+	}
+	poolURL := strings.TrimSpace(c.String("pool"))
+	poolClient := pool.NewClient(poolURL)
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	relays, err := poolClient.FetchRelays(ctx)
+	cancel()
+	if err != nil {
+		log.Debugf("pool lookup failed for relay_id=%s, using legacy fallback: %v", relayID, err)
+		return
+	}
+	for _, relay := range relays {
+		if relay.RelayID == relayID {
+			applyRelayToOptions(crocOptions, relay)
+			log.Infof("resolved relay_id=%s from pool for receiver", relayID)
+			return
+		}
+	}
+	log.Debugf("relay_id=%s not found in pool response, using legacy fallback", relayID)
+}
+
+func applyRelayToOptions(crocOptions *croc.Options, relay pool.Relay) {
+	if len(relay.Ports) > 0 {
+		if relay.IPv4 != "" {
+			crocOptions.RelayAddress = net.JoinHostPort(relay.IPv4, relay.Ports[0])
+		}
+		if relay.IPv6 != "" {
+			crocOptions.RelayAddress6 = net.JoinHostPort(relay.IPv6, relay.Ports[0])
+		}
+		crocOptions.RelayPorts = relay.Ports
+	}
+	if relay.Password != "" {
+		crocOptions.RelayPassword = relay.Password
+	}
 }
diff --git a/src/croc/croc.go b/src/croc/croc.go
index 34d334786..6fed8647f 100644
--- a/src/croc/croc.go
+++ b/src/croc/croc.go
@@ -37,6 +37,7 @@ import (
 	"github.com/schollz/croc/v10/src/crypt"
 	"github.com/schollz/croc/v10/src/message"
 	"github.com/schollz/croc/v10/src/models"
+	"github.com/schollz/croc/v10/src/pool"
 	"github.com/schollz/croc/v10/src/tcp"
 	"github.com/schollz/croc/v10/src/utils"
 )
@@ -151,6 +152,8 @@ type Client struct {
 
 	// ctx.go for graceful shutdown
 	*stop
+
+	normalizedSharedSecret string
 }
 
 // Chunk contains information about the
@@ -204,6 +207,13 @@ func New(ops Options) (c *Client, err error) {
 	c.Options = ops
 	Debug(c.Options.Debug)
 
+	_, parsedSecret := pool.ParseTransferCode(c.Options.SharedSecret)
+	if parsedSecret == "" {
+		c.normalizedSharedSecret = c.Options.SharedSecret
+	} else {
+		c.normalizedSharedSecret = parsedSecret
+	}
+
 	// redirect stderr to null if quiet mode is enabled
 	if c.Options.Quiet {
 		devNull, err := os.OpenFile(os.DevNull, os.O_WRONLY, 0)
@@ -212,13 +222,13 @@ func New(ops Options) (c *Client, err error) {
 		}
 	}
 
-	if len(c.Options.SharedSecret) < 6 {
+	if len(c.normalizedSharedSecret) < 6 {
 		err = fmt.Errorf("code is too short")
 		return
 	}
 	// Create a hash of part of the shared secret to use as the room name
 	hashExtra := "croc"
-	roomNameBytes := sha256.Sum256([]byte(c.Options.SharedSecret[:4] + hashExtra))
+	roomNameBytes := sha256.Sum256([]byte(c.normalizedSharedSecret[:4] + hashExtra))
 	c.Options.RoomName = hex.EncodeToString(roomNameBytes[:])
 
 	c.conn = make([]*comm.Comm, 16)
@@ -257,7 +267,7 @@ func New(ops Options) (c *Client, err error) {
 
 	// initialize pake for recipient
 	if !c.Options.IsSender {
-		c.Pake, err = pake.InitCurve([]byte(c.Options.SharedSecret[5:]), 0, c.Options.Curve)
+		c.Pake, err = pake.InitCurve([]byte(c.normalizedSharedSecret[5:]), 0, c.Options.Curve)
 	}
 	if err != nil {
 		return
@@ -760,7 +770,7 @@ On the other computer run:
 			log.Debugf("banner: %s", banner)
 			log.Debugf("connection established: %+v", conn)
 			var kB []byte
-			B, _ := pake.InitCurve([]byte(c.Options.SharedSecret[5:]), 1, c.Options.Curve)
+			B, _ := pake.InitCurve([]byte(c.normalizedSharedSecret[5:]), 1, c.Options.Curve)
 			for {
 				if err := c.ctxErr(); err != nil {
 					errchan <- err
@@ -1031,7 +1041,7 @@ func (c *Client) Receive() (err error) {
 		err = func() (err error) {
 			var A *pake.Pake
 			var data []byte
-			A, err = pake.InitCurve([]byte(c.Options.SharedSecret[5:]), 0, c.Options.Curve)
+			A, err = pake.InitCurve([]byte(c.normalizedSharedSecret[5:]), 0, c.Options.Curve)
 			if err != nil {
 				return err
 			}
@@ -1455,7 +1465,7 @@ func (c *Client) processMessagePake(m message.Message) (err error) {
 	if c.Options.IsSender {
 		// initialize curve based on the recipient's choice
 		log.Debugf("using curve %s", string(m.Bytes2))
-		c.Pake, err = pake.InitCurve([]byte(c.Options.SharedSecret[5:]), 1, string(m.Bytes2))
+		c.Pake, err = pake.InitCurve([]byte(c.normalizedSharedSecret[5:]), 1, string(m.Bytes2))
 		if err != nil {
 			log.Error(err)
 			return
diff --git a/src/croc/federated_pool_test.go b/src/croc/federated_pool_test.go
new file mode 100644
index 000000000..eed84aeed
--- /dev/null
+++ b/src/croc/federated_pool_test.go
@@ -0,0 +1,178 @@
+package croc
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/schollz/croc/v10/src/pool"
+	"github.com/schollz/croc/v10/src/tcp"
+	"github.com/schollz/croc/v10/src/utils"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func freeLocalPort(t *testing.T) string {
+	t.Helper()
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+	defer ln.Close()
+	_, port, err := net.SplitHostPort(ln.Addr().String())
+	require.NoError(t, err)
+	return port
+}
+
+func waitForPoolReady(t *testing.T, baseURL string) {
+	t.Helper()
+	client := pool.NewClient(baseURL)
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
+		_, err := client.FetchRelays(ctx)
+		cancel()
+		if err == nil {
+			return
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	t.Fatalf("pool server did not become ready at %s", baseURL)
+}
+
+func TestFederatedPoolEndToEnd(t *testing.T) {
+	poolPort := freeLocalPort(t)
+	relayPortA := freeLocalPort(t)
+	relayPortB := freeLocalPort(t)
+
+	poolListen := net.JoinHostPort("127.0.0.1", poolPort)
+	poolURL := fmt.Sprintf("http://%s", poolListen)
+
+	poolServer := pool.NewServer(poolListen)
+	poolServer.HeartbeatTimeout = 30 * time.Second
+	poolServer.CleanupInterval = 60 * time.Second
+	poolServer.AllowPrivateIPs = true
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go func() {
+		_ = poolServer.Start(ctx)
+	}()
+	waitForPoolReady(t, poolURL)
+
+	go func() {
+		_ = tcp.Run("debug", "127.0.0.1", relayPortB, "pass123")
+	}()
+	time.Sleep(100 * time.Millisecond)
+	go func() {
+		_ = tcp.Run("debug", "127.0.0.1", relayPortA, "pass123", relayPortB)
+	}()
+	time.Sleep(200 * time.Millisecond)
+
+	poolClient := pool.NewClient(poolURL)
+	registerCtx, registerCancel := context.WithTimeout(context.Background(), 2*time.Second)
+	registerResp, err := poolClient.Register(registerCtx, pool.RegisterRequest{
+		IPv4:     "127.0.0.1",
+		Ports:    []string{relayPortA, relayPortB},
+		Password: "pass123",
+	})
+	registerCancel()
+	require.NoError(t, err)
+	require.NotEmpty(t, registerResp.RelayID)
+
+	relayCode := utils.GetRandomName(registerResp.RelayID)
+	parsedRelayID, parsedSecret := pool.ParseTransferCode(relayCode)
+	require.Equal(t, registerResp.RelayID, parsedRelayID)
+	require.NotEmpty(t, parsedSecret)
+
+	sharedTempDir := t.TempDir()
+	sendFile := filepath.Join(sharedTempDir, "federated-pool-send.txt")
+	receivedFile := "federated-pool-send.txt"
+	defer os.Remove(receivedFile)
+	require.NoError(t, os.WriteFile(sendFile, []byte("hello from federated pool test"), 0o644))
+
+	sender, err := New(Options{
+		IsSender:      true,
+		SharedSecret:  relayCode,
+		Debug:         true,
+		RelayAddress:  net.JoinHostPort("127.0.0.1", relayPortA),
+		RelayPorts:    []string{relayPortA},
+		RelayPassword: "pass123",
+		Stdout:        false,
+		NoPrompt:      true,
+		DisableLocal:  true,
+		Curve:         "siec",
+		Overwrite:     true,
+	})
+	require.NoError(t, err)
+
+	receiveCtx, receiveCancel := context.WithTimeout(context.Background(), 2*time.Second)
+	relays, err := poolClient.FetchRelays(receiveCtx)
+	receiveCancel()
+	require.NoError(t, err)
+	require.NotEmpty(t, relays)
+
+	selectedRelay, found := pool.Relay{}, false
+	for _, r := range relays {
+		if r.RelayID == parsedRelayID {
+			selectedRelay = r
+			found = true
+			break
+		}
+	}
+	require.True(t, found)
+
+	receiver, err := New(Options{
+		IsSender:      false,
+		SharedSecret:  relayCode,
+		Debug:         true,
+		RelayAddress:  net.JoinHostPort(selectedRelay.IPv4, selectedRelay.Ports[0]),
+		RelayPassword: "pass123", // Password obtained out-of-band (not from pool per proposal)
+		Stdout:        false,
+		NoPrompt:      true,
+		DisableLocal:  true,
+		Curve:         "siec",
+		Overwrite:     true,
+	})
+	require.NoError(t, err)
+
+	filesInfo, emptyFolders, totalNumberFolders, err := GetFilesInfo([]string{sendFile}, false, false, []string{})
+	require.NoError(t, err)
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+	errCh := make(chan error, 2)
+
+	go func() {
+		defer wg.Done()
+		errCh <- sender.Send(filesInfo, emptyFolders, totalNumberFolders)
+	}()
+	time.Sleep(150 * time.Millisecond)
+	go func() {
+		defer wg.Done()
+		errCh <- receiver.Receive()
+	}()
+
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(20 * time.Second):
+		t.Fatal("timed out waiting for federated transfer")
+	}
+	close(errCh)
+	for transferErr := range errCh {
+		require.NoError(t, transferErr)
+	}
+
+	b, err := os.ReadFile(receivedFile)
+	require.NoError(t, err)
+	assert.Equal(t, "hello from federated pool test", string(b))
+}
diff --git a/src/models/constants.go b/src/models/constants.go
index 1622518ca..0455a62ec 100644
--- a/src/models/constants.go
+++ b/src/models/constants.go
@@ -17,11 +17,21 @@ const TCP_BUFFER_SIZE = 1024 * 64
 
 // DEFAULT_RELAY is the default relay used (can be set using --relay)
 var (
-	DEFAULT_RELAY      = "croc.schollz.com"
-	DEFAULT_RELAY6     = "croc6.schollz.com"
-	DEFAULT_PORT       = "9009"
-	DEFAULT_PASSPHRASE = "pass123"
-	INTERNAL_DNS       = false
+	DEFAULT_RELAY       = "croc.schollz.com"
+	DEFAULT_RELAY6      = "croc6.schollz.com"
+	DEFAULT_PORT        = "9009"
+	DEFAULT_PASSPHRASE  = "pass123"
+	DEFAULT_POOL_URL    = "http://croc.schollz.com:9000"
+	DEFAULT_POOL_LISTEN = "0.0.0.0:9000"
+	INTERNAL_DNS        = false
+)
+
+const (
+	RELAY_STATUS_ACTIVE     = "active"
+	RELAY_STATUS_INACTIVE   = "inactive"
+	POOL_HEARTBEAT_TIMEOUT  = 30 * time.Second
+	POOL_HEARTBEAT_INTERVAL = 10 * time.Second
+	POOL_CLEANUP_INTERVAL   = 30 * time.Second
 )
 
 // publicDNS are servers to be queried if a local lookup fails
diff --git a/src/pool/client.go b/src/pool/client.go
new file mode 100644
index 000000000..9a4b5c194
--- /dev/null
+++ b/src/pool/client.go
@@ -0,0 +1,126 @@
+package pool
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"math/rand/v2"
+	"net"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/schollz/croc/v10/src/models"
+)
+
+type Client struct {
+	BaseURL    string
+	HTTPClient *http.Client
+	cache      map[string]Relay
+}
+
+func NewClient(baseURL string) *Client {
+	baseURL = strings.TrimRight(strings.TrimSpace(baseURL), "/")
+	if baseURL == "" {
+		baseURL = models.DEFAULT_POOL_URL
+	}
+	return &Client{
+		BaseURL: baseURL,
+		HTTPClient: &http.Client{
+			Timeout: 3 * time.Second,
+		},
+		cache: make(map[string]Relay),
+	}
+}
+
+func (c *Client) postJSON(ctx context.Context, path string, reqBody interface{}, respBody interface{}) error {
+	payload, err := json.Marshal(reqBody)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.BaseURL+path, bytes.NewReader(payload))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := c.HTTPClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 300 {
+		return fmt.Errorf("pool request failed: %s", resp.Status)
+	}
+	if respBody == nil {
+		return nil
+	}
+	return json.NewDecoder(resp.Body).Decode(respBody)
+}
+
+func (c *Client) Register(ctx context.Context, req RegisterRequest) (RegisterResponse, error) {
+	var resp RegisterResponse
+	err := c.postJSON(ctx, "/register", req, &resp)
+	return resp, err
+}
+
+func (c *Client) Heartbeat(ctx context.Context, relayID string) error {
+	return c.postJSON(ctx, "/heartbeat", HeartbeatRequest{RelayID: relayID}, nil)
+}
+
+func (c *Client) FetchRelays(ctx context.Context) ([]Relay, error) {
+	var resp RelayListResponse
+	err := c.postJSON(ctx, "/relays", map[string]string{}, &resp)
+	if err != nil {
+		return nil, err
+	}
+	for _, relay := range resp.Relays {
+		c.cache[relay.RelayID] = relay
+	}
+	return resp.Relays, nil
+}
+
+func (c *Client) GetCachedRelay(relayID string) (Relay, bool) {
+	relay, ok := c.cache[strings.ToLower(strings.TrimSpace(relayID))]
+	return relay, ok
+}
+
+func (c *Client) ChooseRandomReachableRelay(relays []Relay) (Relay, bool) {
+	reachable := make([]Relay, 0, len(relays))
+	for _, relay := range relays {
+		if isRelayReachable(relay, time.Second) {
+			reachable = append(reachable, relay)
+		}
+	}
+	if len(reachable) == 0 {
+		return Relay{}, false
+	}
+	return reachable[rand.IntN(len(reachable))], true
+}
+
+func isRelayReachable(relay Relay, timeout time.Duration) bool {
+	if len(relay.Ports) == 0 {
+		return false
+	}
+	port := relay.Ports[0]
+	if relay.IPv6 != "" {
+		if canDial(net.JoinHostPort(relay.IPv6, port), timeout) {
+			return true
+		}
+	}
+	if relay.IPv4 != "" {
+		if canDial(net.JoinHostPort(relay.IPv4, port), timeout) {
+			return true
+		}
+	}
+	return false
+}
+
+func canDial(address string, timeout time.Duration) bool {
+	conn, err := net.DialTimeout("tcp", address, timeout)
+	if err != nil {
+		return false
+	}
+	_ = conn.Close()
+	return true
+}
diff --git a/src/pool/pool.go b/src/pool/pool.go
new file mode 100644
index 000000000..0649f6c7d
--- /dev/null
+++ b/src/pool/pool.go
@@ -0,0 +1,194 @@
+package pool
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/schollz/croc/v10/src/models"
+	log "github.com/schollz/logger"
+)
+
+type Server struct {
+	Registry         *Registry
+	HeartbeatTimeout time.Duration
+	CleanupInterval  time.Duration
+	ListenAddress    string
+	AllowPrivateIPs  bool
+	httpServer       *http.Server
+}
+
+func NewServer(listenAddress string) *Server {
+	if strings.TrimSpace(listenAddress) == "" {
+		listenAddress = models.DEFAULT_POOL_LISTEN
+	}
+	return &Server{
+		Registry:         NewRegistry(),
+		HeartbeatTimeout: 30 * time.Second,
+		CleanupInterval:  60 * time.Second,
+		ListenAddress:    listenAddress,
+	}
+}
+
+func (s *Server) Start(ctx context.Context) error {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/register", s.handleRegister)
+	mux.HandleFunc("/heartbeat", s.handleHeartbeat)
+	mux.HandleFunc("/relays", s.handleRelays)
+
+	s.httpServer = &http.Server{
+		Addr:              s.ListenAddress,
+		Handler:           mux,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+
+	go s.runCleanupLoop(ctx)
+	go func() {
+		<-ctx.Done()
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = s.httpServer.Shutdown(shutdownCtx)
+	}()
+
+	log.Infof("pool server listening on %s", s.ListenAddress)
+	err := s.httpServer.ListenAndServe()
+	if errors.Is(err, http.ErrServerClosed) {
+		return nil
+	}
+	return err
+}
+
+func (s *Server) runCleanupLoop(ctx context.Context) {
+	ticker := time.NewTicker(s.CleanupInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			changed := s.Registry.MarkInactiveOlderThan(s.HeartbeatTimeout)
+			if changed > 0 {
+				log.Infof("marked %d relays inactive", changed)
+			}
+		}
+	}
+}
+
+func decodeJSON(r *http.Request, dst interface{}) error {
+	defer r.Body.Close()
+	dec := json.NewDecoder(r.Body)
+	dec.DisallowUnknownFields()
+	return dec.Decode(dst)
+}
+
+func writeJSON(w http.ResponseWriter, status int, payload interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(payload)
+}
+
+func writeErr(w http.ResponseWriter, status int, msg string) {
+	writeJSON(w, status, map[string]interface{}{"ok": false, "error": msg})
+}
+
+func (s *Server) handleRegister(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "method not allowed")
+		return
+	}
+
+	var req RegisterRequest
+	if err := decodeJSON(r, &req); err != nil {
+		writeErr(w, http.StatusBadRequest, fmt.Sprintf("invalid request: %v", err))
+		return
+	}
+
+	if len(req.Ports) < 2 {
+		writeErr(w, http.StatusBadRequest, "ports must contain at least two entries")
+		return
+	}
+	ports, err := SanitizePorts(req.Ports)
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	if strings.TrimSpace(req.IPv6) == "" && strings.TrimSpace(req.IPv4) == "" {
+		writeErr(w, http.StatusBadRequest, "either ipv6 or ipv4 is required")
+		return
+	}
+	if ipv6 := strings.TrimSpace(req.IPv6); ipv6 != "" && !IsPublicIPv6(ipv6) && !s.AllowPrivateIPs {
+		writeErr(w, http.StatusBadRequest, "ipv6 must be a publicly routable address")
+		return
+	}
+	if ipv4 := strings.TrimSpace(req.IPv4); ipv4 != "" && !IsPublicIPv4(ipv4) && !s.AllowPrivateIPs {
+		writeErr(w, http.StatusBadRequest, "ipv4 must be a publicly routable address")
+		return
+	}
+	if strings.TrimSpace(req.RelayID) != "" {
+		log.Debugf("ignoring client-supplied relay_id=%s; main node assigns relay_id", req.RelayID)
+	}
+
+	ipForID := strings.TrimSpace(req.IPv6)
+	if ipForID == "" {
+		ipForID = strings.TrimSpace(req.IPv4)
+	}
+	relayID, err := GenerateRelayIDFromIP(ipForID)
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	relay := Relay{
+		RelayID:  relayID,
+		IPv6:     strings.TrimSpace(req.IPv6),
+		IPv4:     strings.TrimSpace(req.IPv4),
+		Ports:    ports,
+		Password: req.Password,
+	}
+	s.Registry.Upsert(relay)
+	log.Infof("registered relay %s (ipv6=%s ipv4=%s)", relayID, relay.IPv6, relay.IPv4)
+	writeJSON(w, http.StatusOK, RegisterResponse{OK: true, RelayID: relayID})
+}
+
+func (s *Server) handleHeartbeat(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "method not allowed")
+		return
+	}
+	var req HeartbeatRequest
+	if err := decodeJSON(r, &req); err != nil {
+		writeErr(w, http.StatusBadRequest, fmt.Sprintf("invalid request: %v", err))
+		return
+	}
+	id := strings.ToLower(strings.TrimSpace(req.RelayID))
+	if !IsRelayID(id) {
+		writeErr(w, http.StatusBadRequest, "invalid relay_id")
+		return
+	}
+	ok := s.Registry.Heartbeat(id)
+	if !ok {
+		writeErr(w, http.StatusNotFound, "relay_id not found")
+		return
+	}
+	log.Debugf("heartbeat relay %s", id)
+	writeJSON(w, http.StatusOK, map[string]interface{}{"ok": true})
+}
+
+func (s *Server) handleRelays(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "method not allowed")
+		return
+	}
+	// Run cleanup immediately so stale relays are not served.
+	s.Registry.MarkInactiveOlderThan(s.HeartbeatTimeout)
+	relays := s.Registry.ListActive(50)
+	// Strip passwords: relay credentials must be obtained out-of-band.
+	for i := range relays {
+		relays[i].Password = ""
+	}
+	writeJSON(w, http.StatusOK, RelayListResponse{Relays: relays})
+}
diff --git a/src/pool/pool_test.go b/src/pool/pool_test.go
new file mode 100644
index 000000000..329281c65
--- /dev/null
+++ b/src/pool/pool_test.go
@@ -0,0 +1,114 @@
+package pool
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRegisterAssignsRelayIDFromIP(t *testing.T) {
+	s := NewServer("")
+
+	reqBody := RegisterRequest{
+		RelayID:  "ffff", // should be ignored by server
+		IPv4:     "203.0.113.10",
+		Ports:    []string{"9009", "9010"},
+		Password: "pass123",
+	}
+	b, err := json.Marshal(reqBody)
+	assert.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/register", bytes.NewReader(b))
+	req.Header.Set("Content-Type", "application/json")
+	rr := httptest.NewRecorder()
+	s.handleRegister(rr, req)
+
+	assert.Equal(t, http.StatusOK, rr.Code)
+	var resp RegisterResponse
+	assert.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	assert.True(t, resp.OK)
+	assert.NotEqual(t, "ffff", resp.RelayID)
+
+	expected, err := GenerateRelayIDFromIP("203.0.113.10")
+	assert.NoError(t, err)
+	assert.Equal(t, expected, resp.RelayID)
+
+	relay, ok := s.Registry.Get(resp.RelayID)
+	assert.True(t, ok)
+	assert.Equal(t, "203.0.113.10", relay.IPv4)
+}
+
+func TestRelaysEndpointReturnsActiveOnly(t *testing.T) {
+	s := NewServer("")
+	s.Registry.Upsert(Relay{RelayID: "ab12", IPv4: "203.0.113.10", Ports: []string{"9009", "9010"}})
+	s.Registry.Upsert(Relay{RelayID: "cd34", IPv4: "198.51.100.8", Ports: []string{"9009", "9010"}})
+
+	// Mark one relay stale so cleanup marks only that relay inactive.
+	s.Registry.mu.Lock()
+	relay := s.Registry.relays["cd34"]
+	relay.LastHeartbeat = time.Now().UTC().Add(-2 * time.Minute)
+	s.Registry.relays["cd34"] = relay
+	s.Registry.mu.Unlock()
+	s.Registry.MarkInactiveOlderThan(30 * time.Second)
+
+	req := httptest.NewRequest(http.MethodPost, "/relays", http.NoBody)
+	rr := httptest.NewRecorder()
+	s.handleRelays(rr, req)
+
+	assert.Equal(t, http.StatusOK, rr.Code)
+	var resp RelayListResponse
+	assert.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	assert.Len(t, resp.Relays, 1)
+	assert.Equal(t, "ab12", resp.Relays[0].RelayID)
+	for _, r := range resp.Relays {
+		assert.Equal(t, StatusActive, r.Status)
+	}
+}
+
+func TestRegisterSanitizesPorts(t *testing.T) {
+	s := NewServer("")
+
+	reqBody := RegisterRequest{
+		IPv4:  "203.0.113.10",
+		Ports: []string{" 9009 ", "9010"},
+	}
+	b, err := json.Marshal(reqBody)
+	assert.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/register", bytes.NewReader(b))
+	req.Header.Set("Content-Type", "application/json")
+	rr := httptest.NewRecorder()
+	s.handleRegister(rr, req)
+
+	assert.Equal(t, http.StatusOK, rr.Code)
+	var resp RegisterResponse
+	assert.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+
+	relay, ok := s.Registry.Get(resp.RelayID)
+	assert.True(t, ok)
+	assert.Equal(t, []string{"9009", "9010"}, relay.Ports)
+}
+
+func TestRegisterRejectsInvalidPorts(t *testing.T) {
+	s := NewServer("")
+
+	reqBody := RegisterRequest{
+		IPv4:  "203.0.113.10",
+		Ports: []string{"9009", "abc"},
+	}
+	b, err := json.Marshal(reqBody)
+	assert.NoError(t, err)
+
+	req := httptest.NewRequest(http.MethodPost, "/register", bytes.NewReader(b))
+	req.Header.Set("Content-Type", "application/json")
+	rr := httptest.NewRecorder()
+	s.handleRegister(rr, req)
+
+	assert.Equal(t, http.StatusBadRequest, rr.Code)
+	assert.Contains(t, rr.Body.String(), "must be numeric")
+}
diff --git a/src/pool/registry.go b/src/pool/registry.go
new file mode 100644
index 000000000..dfb2b3ff0
--- /dev/null
+++ b/src/pool/registry.go
@@ -0,0 +1,80 @@
+package pool
+
+import (
+	"math/rand/v2"
+	"sync"
+	"time"
+)
+
+// Registry stores relay state in memory.
+type Registry struct {
+	mu     sync.RWMutex
+	relays map[string]Relay
+}
+
+func NewRegistry() *Registry {
+	return &Registry{relays: make(map[string]Relay)}
+}
+
+func (r *Registry) Upsert(relay Relay) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	relay.Status = StatusActive
+	relay.LastHeartbeat = time.Now().UTC()
+	r.relays[relay.RelayID] = relay
+}
+
+func (r *Registry) Heartbeat(relayID string) bool {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	relay, ok := r.relays[relayID]
+	if !ok {
+		return false
+	}
+	relay.Status = StatusActive
+	relay.LastHeartbeat = time.Now().UTC()
+	r.relays[relayID] = relay
+	return true
+}
+
+func (r *Registry) Get(relayID string) (Relay, bool) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	relay, ok := r.relays[relayID]
+	return relay, ok
+}
+
+func (r *Registry) MarkInactiveOlderThan(timeout time.Duration) int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	now := time.Now().UTC()
+	count := 0
+	for id, relay := range r.relays {
+		if now.Sub(relay.LastHeartbeat) > timeout && relay.Status != StatusInactive {
+			relay.Status = StatusInactive
+			r.relays[id] = relay
+			count++
+		}
+	}
+	return count
+}
+
+func (r *Registry) ListActive(limit int) []Relay {
+	r.mu.RLock()
+	relays := make([]Relay, 0, len(r.relays))
+	for _, relay := range r.relays {
+		if relay.Status == StatusActive {
+			relays = append(relays, relay)
+		}
+	}
+	r.mu.RUnlock()
+
+	rand.Shuffle(len(relays), func(i, j int) {
+		relays[i], relays[j] = relays[j], relays[i]
+	})
+
+	if limit > 0 && len(relays) > limit {
+		relays = relays[:limit]
+	}
+	return relays
+}
diff --git a/src/pool/registry_test.go b/src/pool/registry_test.go
new file mode 100644
index 000000000..3fbb72639
--- /dev/null
+++ b/src/pool/registry_test.go
@@ -0,0 +1,40 @@
+package pool
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRegistryUpsertHeartbeatAndList(t *testing.T) {
+	r := NewRegistry()
+	r.Upsert(Relay{RelayID: "ab12", IPv4: "203.0.113.10", Ports: []string{"9009", "9010"}})
+
+	relay, ok := r.Get("ab12")
+	assert.True(t, ok)
+	assert.Equal(t, StatusActive, relay.Status)
+
+	assert.True(t, r.Heartbeat("ab12"))
+	assert.False(t, r.Heartbeat("ffff"))
+
+	active := r.ListActive(50)
+	assert.Len(t, active, 1)
+}
+
+func TestRegistryMarkInactiveOlderThan(t *testing.T) {
+	r := NewRegistry()
+	r.Upsert(Relay{RelayID: "ab12", IPv4: "203.0.113.10", Ports: []string{"9009", "9010"}})
+
+	r.mu.Lock()
+	relay := r.relays["ab12"]
+	relay.LastHeartbeat = time.Now().UTC().Add(-2 * time.Minute)
+	r.relays["ab12"] = relay
+	r.mu.Unlock()
+
+	changed := r.MarkInactiveOlderThan(30 * time.Second)
+	assert.Equal(t, 1, changed)
+
+	relay, _ = r.Get("ab12")
+	assert.Equal(t, StatusInactive, relay.Status)
+}
diff --git a/src/pool/types.go b/src/pool/types.go
new file mode 100644
index 000000000..c8c0d2a6c
--- /dev/null
+++ b/src/pool/types.go
@@ -0,0 +1,44 @@
+package pool
+
+import "time"
+
+const (
+	StatusActive   = "active"
+	StatusInactive = "inactive"
+)
+
+// Relay describes a relay entry exposed by the pool API.
+type Relay struct {
+	RelayID       string    `json:"relay_id"`
+	IPv6          string    `json:"ipv6,omitempty"`
+	IPv4          string    `json:"ipv4,omitempty"`
+	Ports         []string  `json:"ports"`
+	Password      string    `json:"password,omitempty"`
+	Status        string    `json:"status"`
+	LastHeartbeat time.Time `json:"last_heartbeat"`
+}
+
+// RegisterRequest is the body for POST /register.
+type RegisterRequest struct {
+	RelayID  string   `json:"relay_id,omitempty"`
+	IPv6     string   `json:"ipv6,omitempty"`
+	IPv4     string   `json:"ipv4,omitempty"`
+	Ports    []string `json:"ports"`
+	Password string   `json:"password,omitempty"`
+}
+
+// RegisterResponse is the response for POST /register.
+type RegisterResponse struct {
+	OK      bool   `json:"ok"`
+	RelayID string `json:"relay_id"`
+}
+
+// HeartbeatRequest is the body for POST /heartbeat.
+type HeartbeatRequest struct {
+	RelayID string `json:"relay_id"`
+}
+
+// RelayListResponse is the response for POST /relays.
+type RelayListResponse struct {
+	Relays []Relay `json:"relays"`
+}
diff --git a/src/pool/utils.go b/src/pool/utils.go
new file mode 100644
index 000000000..29bb275b5
--- /dev/null
+++ b/src/pool/utils.go
@@ -0,0 +1,142 @@
+package pool
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"net"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+var relayIDRegex = regexp.MustCompile(`^[a-f0-9]{4}$`)
+
+var privateIPv4Blocks = mustParseCIDRs([]string{
+	"10.0.0.0/8",
+	"172.16.0.0/12",
+	"192.168.0.0/16",
+	"100.64.0.0/10",
+})
+
+func mustParseCIDRs(cidrs []string) []*net.IPNet {
+	blocks := make([]*net.IPNet, 0, len(cidrs))
+	for _, cidr := range cidrs {
+		_, block, err := net.ParseCIDR(cidr)
+		if err != nil {
+			panic(fmt.Sprintf("pool: invalid CIDR %q: %v", cidr, err))
+		}
+		blocks = append(blocks, block)
+	}
+	return blocks
+}
+
+// GenerateRelayIDFromIP returns a deterministic 4-char relay ID from an IP string.
+func GenerateRelayIDFromIP(ip string) (string, error) {
+	trimmed := strings.TrimSpace(ip)
+	if trimmed == "" {
+		return "", errors.New("ip is required")
+	}
+	parsed := net.ParseIP(trimmed)
+	if parsed == nil {
+		return "", fmt.Errorf("invalid ip: %s", ip)
+	}
+	sum := sha256.Sum256([]byte(parsed.String()))
+	return hex.EncodeToString(sum[:2]), nil
+}
+
+func IsRelayID(s string) bool {
+	return relayIDRegex.MatchString(strings.ToLower(strings.TrimSpace(s)))
+}
+
+func SanitizePorts(ports []string) ([]string, error) {
+	if len(ports) < 2 {
+		return nil, errors.New("ports must contain at least two entries")
+	}
+	sanitized := make([]string, 0, len(ports))
+	for _, p := range ports {
+		trimmed := strings.TrimSpace(p)
+		if trimmed == "" {
+			return nil, errors.New("ports entries must be non-empty")
+		}
+		port, err := strconv.Atoi(trimmed)
+		if err != nil {
+			return nil, fmt.Errorf("invalid port %q: must be numeric", p)
+		}
+		if port < 1 || port > 65535 {
+			return nil, fmt.Errorf("invalid port %q: must be in range 1-65535", p)
+		}
+		sanitized = append(sanitized, trimmed)
+	}
+	return sanitized, nil
+}
+
+// ParseTransferCode splits a code into relayID + secret for federated format.
+// Legacy codes return empty relayID and the original code as secret.
+func ParseTransferCode(code string) (relayID string, secret string) {
+	code = strings.TrimSpace(code)
+	if code == "" {
+		return "", ""
+	}
+	parts := strings.Split(code, "-")
+	if len(parts) < 3 {
+		return "", code
+	}
+	candidate := strings.ToLower(parts[0])
+	if !IsRelayID(candidate) {
+		return "", code
+	}
+	// The second segment must be the 4-digit pin in federated format.
+	if len(parts[1]) != 4 {
+		return "", code
+	}
+	for _, ch := range parts[1] {
+		if ch < '0' || ch > '9' {
+			return "", code
+		}
+	}
+	secretPart := strings.Join(parts[1:], "-")
+	if strings.TrimSpace(secretPart) == "" {
+		return "", code
+	}
+	return candidate, secretPart
+}
+
+func IsPublicIPv4(ipStr string) bool {
+	ip := net.ParseIP(strings.TrimSpace(ipStr))
+	if ip == nil {
+		return false
+	}
+	ip = ip.To4()
+	if ip == nil {
+		return false
+	}
+	if ip.IsLoopback() || ip.IsMulticast() || ip.IsLinkLocalUnicast() || ip.IsUnspecified() {
+		return false
+	}
+
+	// RFC1918 + CGNAT
+	for _, block := range privateIPv4Blocks {
+		if block.Contains(ip) {
+			return false
+		}
+	}
+	return true
+}
+
+func IsPublicIPv6(ipStr string) bool {
+	ip := net.ParseIP(strings.TrimSpace(ipStr))
+	if ip == nil || ip.To4() != nil {
+		return false
+	}
+	if ip.IsLoopback() || ip.IsMulticast() || ip.IsLinkLocalUnicast() || ip.IsUnspecified() {
+		return false
+	}
+	// Unique local addresses fc00::/7 are not public.
+	_, ula, _ := net.ParseCIDR("fc00::/7")
+	if ula.Contains(ip) {
+		return false
+	}
+	return true
+}
diff --git a/src/pool/utils_test.go b/src/pool/utils_test.go
new file mode 100644
index 000000000..8f87bf5a9
--- /dev/null
+++ b/src/pool/utils_test.go
@@ -0,0 +1,63 @@
+package pool
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestGenerateRelayIDFromIP(t *testing.T) {
+	id1, err := GenerateRelayIDFromIP("203.0.113.10")
+	assert.NoError(t, err)
+	assert.Len(t, id1, 4)
+
+	id2, err := GenerateRelayIDFromIP("203.0.113.10")
+	assert.NoError(t, err)
+	assert.Equal(t, id1, id2)
+}
+
+func TestParseTransferCode(t *testing.T) {
+	relayID, secret := ParseTransferCode("ab12-7123-yellow-apple")
+	assert.Equal(t, "ab12", relayID)
+	assert.Equal(t, "7123-yellow-apple", secret)
+
+	relayID, secret = ParseTransferCode("7123-yellow-apple")
+	assert.Equal(t, "", relayID)
+	assert.Equal(t, "7123-yellow-apple", secret)
+}
+
+func TestPublicIPValidation(t *testing.T) {
+	assert.True(t, IsPublicIPv4("8.8.8.8"))
+	assert.False(t, IsPublicIPv4("192.168.1.10"))
+	assert.False(t, IsPublicIPv4("127.0.0.1"))
+
+	assert.True(t, IsPublicIPv6("2001:4860:4860::8888"))
+	assert.False(t, IsPublicIPv6("::1"))
+	assert.False(t, IsPublicIPv6("fc00::1"))
+}
+
+func TestSanitizePorts(t *testing.T) {
+	t.Run("trims and accepts valid", func(t *testing.T) {
+		ports, err := SanitizePorts([]string{" 9009 ", "9010"})
+		assert.NoError(t, err)
+		assert.Equal(t, []string{"9009", "9010"}, ports)
+	})
+
+	t.Run("rejects non-numeric", func(t *testing.T) {
+		_, err := SanitizePorts([]string{"9009", "foo"})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "must be numeric")
+	})
+
+	t.Run("rejects out of range", func(t *testing.T) {
+		_, err := SanitizePorts([]string{"9009", "70000"})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "range 1-65535")
+	})
+
+	t.Run("rejects empty", func(t *testing.T) {
+		_, err := SanitizePorts([]string{"9009", "   "})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "non-empty")
+	})
+}
diff --git a/src/utils/utils.go b/src/utils/utils.go
index fc50c7e45..3ca32ad01 100644
--- a/src/utils/utils.go
+++ b/src/utils/utils.go
@@ -247,24 +247,39 @@ func SHA256(s string) string {
 	return hex.EncodeToString(sha.Sum(nil))
 }
 
-// PublicIP returns public ip address
-func PublicIP() (ip string, err error) {
-	// ask ipv4.icanhazip.com for the public ip
-	// by making http request
-	// if the request fails, return nothing
-	resp, err := http.Get("http://ipv4.icanhazip.com")
+// PublicIPv4 returns the public IPv4 address.
+func PublicIPv4() (ip string, err error) {
+	return publicIP("http://ipv4.icanhazip.com")
+}
+
+// PublicIPv6 returns the public IPv6 address, if available.
+func PublicIPv6() (ip string, err error) {
+	return publicIP("http://ipv6.icanhazip.com")
+}
+
+func publicIP(url string) (ip string, err error) {
+	client := &http.Client{Timeout: 5 * time.Second}
+	resp, err := client.Get(url)
 	if err != nil {
-		return
+		return "", fmt.Errorf("failed to request public IP from %s: %w", url, err)
 	}
 	defer resp.Body.Close()
 
-	// read the body of the response
-	// and return the ip address
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("unexpected status code from %s: %d", url, resp.StatusCode)
+	}
+
 	buf := new(bytes.Buffer)
-	buf.ReadFrom(resp.Body)
+	if _, err = buf.ReadFrom(resp.Body); err != nil {
+		return "", fmt.Errorf("failed to read response body from %s: %w", url, err)
+	}
+
 	ip = strings.TrimSpace(buf.String())
+	if ip == "" {
+		return "", fmt.Errorf("empty response body from %s", url)
+	}
 
-	return
+	return ip, nil
 }
 
 // LocalIP returns local ip address
@@ -296,13 +311,22 @@ func GenerateRandomPin() string {
 	return s
 }
 
-// GetRandomName returns mnemonicoded random name
-func GetRandomName() string {
+// GetRandomName returns a random transfer code.
+// If relayID is provided, format is <relay_id>-<pin>-<words>.
+func GetRandomName(relayID ...string) string {
 	var result []string
 	bs := make([]byte, NbBytesWords)
-	rand.Read(bs)
+	n, err := rand.Read(bs)
+	if err != nil || n != len(bs) {
+		log.Error("failed to read random bytes for GetRandomName: ", err)
+		return ""
+	}
 	result = mnemonicode.EncodeWordList(result, bs)
-	return GenerateRandomPin() + "-" + strings.Join(result, "-")
+	secret := GenerateRandomPin() + "-" + strings.Join(result, "-")
+	if len(relayID) > 0 && strings.TrimSpace(relayID[0]) != "" {
+		return strings.TrimSpace(strings.ToLower(relayID[0])) + "-" + secret
+	}
+	return secret
 }
 
 // ByteCountDecimal converts bytes to human readable byte string
diff --git a/src/utils/utils_test.go b/src/utils/utils_test.go
index 7d597bbdf..4bbeecacf 100644
--- a/src/utils/utils_test.go
+++ b/src/utils/utils_test.go
@@ -213,7 +213,7 @@ func TestHashFile(t *testing.T) {
 }
 
 func TestPublicIP(t *testing.T) {
-	ip, err := PublicIP()
+	ip, err := PublicIPv4()
 	fmt.Println(ip)
 	assert.True(t, strings.Contains(ip, ".") || strings.Contains(ip, ":"))
 	assert.Nil(t, err)
@@ -229,6 +229,11 @@ func TestGetRandomName(t *testing.T) {
 	name := GetRandomName()
 	fmt.Println(name)
 	assert.NotEmpty(t, name)
+	assert.GreaterOrEqual(t, strings.Count(name, "-"), 1)
+
+	nameWithRelay := GetRandomName("ab12")
+	assert.True(t, strings.HasPrefix(nameWithRelay, "ab12-"))
+	assert.GreaterOrEqual(t, strings.Count(nameWithRelay, "-"), 2)
 }
 
 func intSliceSame(a, b []int) bool {