Worldshaper/docs/request-analysis-vps.md

Request Analysis On Debian 12 VPS

This setup runs the request-analysis worker on the VPS only when needed.

How It Works

• the API server accepts pending launcher requests
• when a new pending request is created, the server schedules the worker
• only one worker run is active at a time
• if more pending requests remain after a run finishes, the server schedules another pass
• you can also trigger a run manually through POST /api/launcher-requests/process-pending

The worker itself still uses DeepSeek's hosted API, so the VPS is coordinating queue work instead of doing local inference.

Required Environment

Recommended env file:

/srv/worldshaper/shared/worldshaper.env

Example:

DEEPSEEK_API_KEY=your-key-here
REQUEST_ANALYZER_AUTORUN=1
REQUEST_ANALYZER_PROVIDER=deepseek
REQUEST_ANALYZER_MODEL=deepseek-v4-flash
REQUEST_ANALYZER_PROMOTE_THRESHOLD=0.85
REQUEST_ANALYZER_THINKING=disabled

PM2 Deploy Hook

The sample post-receive hook in scripts/vps-post-receive.sample.sh now:

• loads /srv/worldshaper/shared/worldshaper.env if present
• restarts PM2 with --update-env
• passes the request-analysis environment through on restart/start

Manual Trigger

If you want to force a queue run:

curl -X POST http://127.0.0.1:5180/api/launcher-requests/process-pending

Notes

• autorun is opt-in through REQUEST_ANALYZER_AUTORUN=1
• the worker only launches if pending requests exist
• DeepSeek credentials stay on the VPS in the shared env file, not in the repo