freight-client-onboard

name

freight-client-onboard

description

Orchestrate complete client onboarding workflow for freight broker AI service. Automates VPS creation, OpenClaw installation, Twilio SMS webhook setup, skill deployment, and testing. Provides dashboard API for managing multiple clients. Use when onboarding a new freight broker client, checking onboarding status, or managing the client fleet. Triggered by "onboard client", "new client", "client setup", "onboarding status", "create client", or "provision new broker".

Freight Client Onboard

Complete onboarding automation for new freight broker clients. One command = fully configured VPS with OpenClaw + Twilio SMS + all skills.

Architecture (Twilio SMS Flow)

Broker SMS → Twilio → HTTP POST → OpenClaw VPS → Skill → Twilio API → Broker SMS

No macOS server needed - just Twilio + VPS.

Onboarding Workflow

1. Create VPS → Cloud server provisioned
2. Install Dependencies → Python, Twilio SDK, OCR libs
3. Deploy Skills → All 11 freight skills copied
4. Start Webhook Server → SMS listener on port 8080
5. Configure Twilio → Point number to VPS webhook

Setup

# VPS credentials (DigitalOcean, Hetzner, or AWS)
export VPS_PROVIDER=digitalocean
export VPS_API_KEY=dop_v1_xxxxxx

# SSH key for VPS access
export VPS_SSH_PRIVATE_KEY=~/.ssh/id_rsa

Usage

Full onboarding (one command)

cd skills/freight-client-onboard/scripts
python3 onboard_client.py --name "ABC Trucking" --email "[e-mail]" --phone "[phone]"

Dry run (test without creating resources)

python3 onboard_client.py --name "Test Broker" --email "[e-mail]" --phone "[phone]" --dry-run

View onboarding history

python3 onboard_client.py --history

Start dashboard API

python3 dashboard_api.py --port 8080

Post-Onboarding (Manual Steps)

After the script runs:

1. Buy Twilio Number

   • Go to twilio.com/console/phone-numbers/search
   • Buy a local number (~$1/month)

2. Configure Webhook

   • Phone Numbers → Manage → Active Numbers
   • Click your number
   • Messaging → Webhook
   • URL: http://vps-ip:8080/webhook/sms
   • Method: HTTP POST

3. Test

   • Text "help" to the Twilio number
   • Should receive command list

Dashboard API

Web API for managing clients programmatically.

Endpoint	Method	Description
/api/status	GET	Server health
/api/clients	GET	List all clients
/api/clients/{id}	GET	Client details
/api/clients	POST	Create new client (triggers onboarding)

Create client via API

curl -X POST http://localhost:8080/api/clients \
  -H "Content-Type: application/json" \
  -d '{"name":"ABC Trucking","email":"[e-mail]","phone":"[phone]"}'

SMS Output Example

🚀 STARTING ONBOARDING: ABC Trucking
==================================================

📦 Step 1: Creating VPS...
   ✅ VPS created: CLIENT-20251218000001
   📍 IP: 192.0.2.100

⏳ Step 2: Waiting for VPS...
   ✅ VPS ready!

🔧 Step 3: Installing dependencies...
   ✅ Installed: Python, Twilio, OCR libs

📁 Step 4: Deploying freight skills...
   ✅ 11 skills deployed

📱 Step 5: Configuring Twilio webhook...
   ⚠️  Pending manual config
   Webhook URL: http://192.0.2.100:8080/webhook/sms

🚀 Step 6: Starting webhook server...
   ✅ Server running on port 8080

==================================================
✅ ONBOARDING COMPLETE!
Client ID: CLIENT-20251218000001
VPS IP: 192.0.2.100
Webhook: http://192.0.2.100:8080/webhook/sms

⚠️  ACTION REQUIRED:
1. Buy Twilio phone number
2. Configure webhook: http://192.0.2.100:8080/webhook/sms
3. Share number with broker
4. Test: text 'help'

Frontend Dashboard

Build a simple web UI that calls the dashboard API:

<!-- Client list -->
<script>
fetch('http://localhost:8080/api/clients')
  .then(r => r.json())
  .then(data => {
    data.clients.forEach(c => {
      console.log(`${c.name}: ${c.vps_ip} (${c.status})`);
    });
  });
</script>

Monitoring

• Onboarding logs: ~/.freight-broker/onboarding.log
• Client records: ~/.freight-broker/clients.json
• VPS status: vps_manager.py --status CLIENT-ID
• Webhook logs: /var/log/webhook.log (on VPS)

Troubleshooting

• "VPS_API_KEY not configured" → Set env var with your cloud provider key
• SSH timeout → Check firewall, verify SSH key is added to provider
• Webhook not responding → Check port 8080 is open, server is running
• Twilio errors → Verify Account SID and Auth Token in VPS env vars

Integrations

This skill uses the following external services. See INTEGRATIONS.md for detailed setup instructions, API documentation links, and implementation guidance.

Service	Purpose	Section in INTEGRATIONS.md
VPS Provider (DigitalOcean/Hetzner/AWS)	Client infrastructure	Refer to this SKILL.md
Twilio	SMS for each client	Shared Infrastructure: Twilio
Telnyx	Alternative SMS provider	Shared Infrastructure: Telnyx

See INTEGRATIONS.md for complete integration architecture

Twilio Costs

• Phone number: $1/month
• Inbound SMS: Free
• Outbound SMS: $0.0075/message
• 1000 messages/month = ~$8.50 total per client