← Back to Docs

Hardware Sharing Architecture

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

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, USB/IP, 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 USB/IP 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. USB/IP exports J-Link/ST-Link
4. Heartbeat to server every 30s
💻 OPERATOR Machine
Uses Remote Hardware
1. WireGuard connected (10.99.0.8)
2. USB/IP client connects to host
3. Device appears as local USB
4. OpenOCD/Claude Code uses it
↓
USB/IP over VPN
🔌
Physical USB Device
J-Link, ST-Link, Nu-Link
🎯
Virtual USB Device
Appears local via USB/IP

💡 Key Insight: USB/IP makes the remote device appear as if it's plugged directly into the operator's computer. OpenOCD and debugging tools work normally—they don't even know the device is remote!

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 USB/IP server, 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"
→ Agent connects via USB/IP → Device appears local → OpenOCD flashes 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
🔌 USB/IP
  • • Linux - Native kernel module
  • • Windows - usbipd-win
  • • macOS - VirtualHere (client only)
  • • Port 3240 - Default USB/IP port
🌐 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. USB/IP server only listens on VPN interface.
🎫
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 + USB/IP server. OPERATOR just needs WireGuard + USB/IP client + 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 → USB/IP
  • • HOST: Exports USB via server
  • • OPERATOR: Connects via client
  • • Through VPN tunnel (encrypted)
  • • Device appears as local USB

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