| 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
- Create VPS → Cloud server provisioned
- Install Dependencies → Python, Twilio SDK, OCR libs
- Deploy Skills → All 11 freight skills copied
- Start Webhook Server → SMS listener on port 8080
- Configure Twilio → Point number to VPS webhook
Setup
export VPS_PROVIDER=digitalocean
export VPS_API_KEY=dop_v1_xxxxxx
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 "ops@abc.com" --phone "+1-555-123-4567"
Dry run (test without creating resources)
python3 onboard_client.py --name "Test Broker" --email "test@test.com" --phone "+1-555-0000" --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:
-
Buy Twilio Number
- Go to twilio.com/console/phone-numbers/search
- Buy a local number (~$1/month)
-
Configure Webhook
- Phone Numbers → Manage → Active Numbers
- Click your number
- Messaging → Webhook
- URL:
http://vps-ip:8080/webhook/sms
- Method: HTTP POST
-
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":"ops@abc.com","phone":"+1-555-123-4567"}'
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:
<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
