# Vercel Sandbox Interaction Notes

## SSH Spike Test Results - February 2, 2026

### What We Learned

**Vercel Sandbox Port Publishing:**
- `--publish-port 2222` exposes the port via HTTPS, NOT raw TCP
- Published ports are accessible via `https://sb-xxx.vercel.run` (HTTP/HTTPS only)
- SSH requires raw TCP, which is NOT supported by Vercel's port publishing
- Connection times out when trying to SSH to the published URL

**File Operations in Sandbox:**
- `sandbox copy <local> <sandbox>:<path>` only works for single files, not directories
- Directories cause "tar: Cannot open: Permission denied" errors
- The sandbox filesystem is at `/vercel/sandbox` (working directory)
- Files must be created using `sandbox exec` with heredocs or echo commands

**Package Management:**
- Sandbox comes with npm pre-installed
- Can install packages with `npm install <package>` in sandbox exec
- The sandbox may have a package.json with `"type": "module"` from previous operations
- Prefer ES modules (.mjs) over CommonJS (.cjs) for modern standards

**Process Management:**
- Can run background processes with `&` in exec commands
- Processes survive after exec command completes
- Can check running processes with `ps aux`

**SSH Server Implementation:**
- ssh2 library works in Vercel Sandbox
- Can bind to port 2222 (non-privileged)
- Server starts successfully and accepts local connections
- JSON-RPC protocol works over SSH exec and shell channels

### Critical Blocker

**SSH over Internet to Vercel Sandbox is NOT possible** because:
1. Vercel only exposes HTTP/HTTPS endpoints
2. SSH requires raw TCP protocol
3. The published port URL (`https://sb-xxx.vercel.run`) is an HTTPS endpoint

### Potential Solutions

**Option 1: WebSocket Tunnel**
- Bot opens WebSocket connection to a tunnel service (like ngrok, localtunnel)
- SSH traffic is wrapped in WebSocket frames
- Requires additional infrastructure

**Option 2: HTTP Admin Interface**
- Replace SSH with HTTPS admin endpoints
- Use Sigma Auth (BAP) for authentication
- Keep REST API but add admin-only routes
- Less secure than SSH but works with Vercel

**Option 3: Use Vercel CLI Directly**
- `sandbox connect` provides shell access
- `sandbox exec` runs commands
- No custom SSH server needed
- Users interact via Vercel CLI, not direct SSH

**Option 4: Alternative Hosting**
- Use Railway, Fly.io, or other platforms that support raw TCP
- Keep Vercel for HTTP layer, use other platform for SSH

### Recommendation

For the ClawNet CLI bot deployment, use **Option 3 (Vercel CLI wrapper)**:

```bash
# Deploy bot to sandbox
clawnet bot deploy --name my-bot --template clark

# Execute commands via Vercel CLI
clawnet bot exec my-bot '{"method":"status"}'
# (Internally runs: sandbox exec <sandbox-id> -- node -e "...")

# Interactive shell
clawnet bot ssh my-bot
# (Internally runs: sandbox connect <sandbox-id>)
```

This avoids the TCP limitation while still providing the desired UX.

### Code Patterns for Sandbox

**Creating files:**
```bash
sandbox exec <id> -- bash -c "cat > file.ts << 'EOF'
<file content>
EOF"
```

**Installing packages:**
```bash
sandbox exec <id> -- npm install ssh2
```

**Running background processes:**
```bash
sandbox exec <id> -- bash -c "node server.js &"
```

**Generating SSH keys:**
```bash
sandbox exec <id> -- ssh-keygen -t rsa -b 2048 -f host_key -N ''
```

### Next Steps

1. Implement HTTP-based admin interface in bot (fallback to SSH)
2. Build ClawNet CLI wrapper around `sandbox` CLI
3. Support both local (SSH) and sandbox (HTTP/Vercel CLI) modes
4. Document the architecture decision