← Back to Docs

Hardware Sharing Architecture

How ProbeCodex enables secure, remote USB debug probe sharing within teams using VPN and remote OpenOCD.

What You'll Learn

🔌
How It Works
Portal coordinates, agent executes
👥
User Workflows
Step-by-step for host and operator
🔒
Security
VPN encryption and access control
🛠️
Technology Stack
WireGuard, remote OpenOCD, TypeScript agent

Key Concept: Coordination vs Control

✅
The Portal IS a Coordination Layer
  • • Manages user authentication and authorization
  • • Distributes VPN configurations securely
  • • Provides hardware discovery and booking
  • • Tracks usage for billing and analytics
❌
The Portal is NOT a Control Layer
  • • Does NOT directly control the agent on your machine
  • • Does NOT start/stop OpenOCD connections
  • • Does NOT manage VPN connections directly
  • • Does NOT execute commands on user devices

Why this matters: The agent runs autonomously on your local machine with full control. The portal simply tells you what hardware is available and who can access it—the actual sharing happens peer-to-peer over VPN.

System Architecture

🌐 Web Portal (probecodex.com)
• User login and organization management
• VPN config download
• Hardware discovery and booking
↓
HTTPS
🖥️ Telemetry Server (Hetzner VPS)
• PostgreSQL database (orgs, users, hardware)
• REST API for registration & heartbeat
• WireGuard VPN server (vpn.probecodex.com:51820)
↓
WireGuard VPN
(encrypted tunnel)
💻 HOST Machine
Shares Hardware
1. WireGuard connected (10.99.0.5)
2. probecodex-agent start
3. OpenOCD binds to 0.0.0.0:13333
4. Heartbeat to server every 30s
💻 OPERATOR Machine
Uses Remote Hardware
1. WireGuard connected (10.99.0.8)
2. GDB connects to host's OpenOCD over VPN
3. Debug as if probe is locally connected
4. Claude Code / GDB uses it normally
↓
GDB over VPN
🔌
Physical USB Probe + OpenOCD
J-Link, ST-Link, Nu-Link on HOST
🎯
Remote GDB Connection
OPERATOR connects via VPN to OpenOCD

💡 Key Insight: The HOST runs OpenOCD locally with the probe, binding to 0.0.0.0 so it's accessible over VPN. The OPERATOR connects GDB to the HOST's OpenOCD — debugging tools work normally, they just point to a remote GDB server.

User Workflows

🏠 HOST: Sharing Your Hardware

1
Setup VPN
Login to portal → /portal/team → Download VPN config → Import to WireGuard app → Connect
2
Register Intent
Go to /portal/hardware → Click "Offer Hardware" → Fill device details (type, MCU, description)
3
Start Agent
Run: probecodex-agent start
Agent auto-detects USB devices, starts OpenOCD bound to VPN, sends heartbeat every 30s
4
Done! Hardware is Live
Portal shows device as "Available" with green badge. Team members can now book it.

🎮 OPERATOR: Using Remote Hardware

1
Connect to VPN
Download VPN config from portal → Import to WireGuard → Connect (get VPN IP like 10.99.0.8)
2
Browse & Book
Go to /portal/hardware → See available devices → Book time slot or connect now
3
Use with Claude Code
Start Claude Code: claude-code
Say: "Connect to the shared J-Link and flash my firmware"
→ GDB connects to remote OpenOCD over VPN → Debug and flash as normal
4
Session Tracked
Portal shows "In Use" with your name. Usage logged for analytics.

Technology Stack

🌐 Portal
  • • Next.js 14 - React framework
  • • TypeScript - Type safety
  • • NextAuth.js - OAuth authentication
  • • Docker - Hetzner deployment
🖥️ Telemetry Server
  • • Node.js + Express - REST API
  • • PostgreSQL 14 - Database
  • • TypeScript - Type safety
  • • Port 3001 - HTTPS endpoint
🔒 VPN Infrastructure
  • • WireGuard - Modern VPN (MIT license)
  • • ChaCha20-Poly1305 - Encryption
  • • Hub-and-spoke - Architecture
  • • 10.99.0.0/24 - Subnet range
🤖 ProbeCodex Agent
  • • TypeScript - Strict typing
  • • Node.js - Runtime
  • • REST API - localhost:9876
  • • Cross-platform - Linux, macOS, Windows
🔌 Remote OpenOCD
  • • All platforms - OpenOCD runs on HOST
  • • GDB port 13333 - Bound to 0.0.0.0
  • • Telnet port 14444 - For diagnostics
  • • No extra drivers - Standard GDB protocol
🌐 Optional: wstunnel
  • • WebSocket tunnel - TCP 443
  • • UDP blocking - Auto-detection
  • • Mobile carriers - Workaround
  • • Open-source - Rust implementation

Security & Privacy

🔐
End-to-End Encryption
All traffic flows through WireGuard VPN with ChaCha20-Poly1305 encryption. Perfect forward secrecy with periodic key rotation.
👤
Organization Isolation
VPN firewall rules ensure peers can only communicate within their organization. No cross-organization traffic possible.
🏠
Local-Only Agent API
Agent REST API binds to 127.0.0.1 only—no remote access. OpenOCD GDB port only accessible over VPN.
🎫
Access Control
Portal manages permissions via organization membership and team roles. Only authorized team members can see and book hardware.

Common Misconceptions

❌ "The portal controls the agent"
Reality: The agent is autonomous and runs on your local machine. The portal provides discovery and coordination—the agent makes its own sharing decisions.
❌ "You need special software on both machines"
Reality: HOST needs agent + WireGuard + OpenOCD. OPERATOR just needs WireGuard + GDB (or Claude Code). Standard tools, nothing proprietary.
❌ "Hardware sharing is only for AI debugging"
Reality: Works with any debugging tool! Use it with Claude Code, manual OpenOCD/GDB, or any tool that supports USB devices.
❌ "The MCP server manages hardware sharing"
Reality: The MCP server (mcp-arm-debug) is for AI debugging. Hardware sharing is managed by probecodex-agent, which is a separate autonomous daemon.

Integration Points

1️⃣ Portal → Telemetry Server
  • • User authentication (OAuth)
  • • Organization/team management
  • • VPN config generation
  • • Booking & queue management
  • • Usage statistics
2️⃣ Agent → Telemetry Server
  • • Device registration
  • • Heartbeat (every 30s)
  • • Session start/stop logging
  • • Usage metrics for billing
3️⃣ MCP Tools → Agent API
  • • hardware.list → GET /api/devices
  • • hardware.connect → POST /api/devices/:id/connect
  • • hardware.disconnect → DELETE /api/devices/:id/connect
4️⃣ Agent → OpenOCD
  • • HOST: Runs OpenOCD bound to 0.0.0.0
  • • OPERATOR: Connects GDB over VPN
  • • Through VPN tunnel (encrypted)
  • • Standard GDB remote protocol

Ready to Try Hardware Sharing?

Team and Enterprise tiers include unlimited hardware sharing with your organization. Set up takes just 10 minutes.

Open Portal DashboardView Full Documentation

📚 Technical Reference

For engineers and developers who want deeper technical details:

  • • Database schemas - PostgreSQL tables for hardware, sessions, VPN peers
  • • API endpoints - Complete REST API reference
  • • Agent source code - TypeScript implementation in mcp-arm-debug repo
  • • VPN configuration - WireGuard setup and sync scripts
  • • Troubleshooting guide - Common issues and solutions

Internal documentation available in DT-Vault:Architecture/Portal-Agent-Hardware-Sharing-Architecture.md