feat(deploy): add free cloud deployment via Render API and Vercel web

Author: biru-codeastromer

.gitignore

@@ -11,6 +11,7 @@ venv/
 *.egg-info/
 node_modules/
 .next/
+.vercel/
 .expo/
 .expo-shared/
 dist/

Makefile

@@ -2,7 +2,7 @@ VENV ?= .venv
 PYTHON ?= $(VENV)/bin/python
 PIP ?= $(VENV)/bin/pip
 
-.PHONY: setup test lint demo paper deploy stop deploy-public stop-public
+.PHONY: setup test lint demo paper deploy stop deploy-public stop-public deploy-vercel
 
 setup:
 	python3 -m venv $(VENV)
@@ -49,3 +49,6 @@ deploy-public:
 
 stop-public:
 	./scripts/stop_public.sh
+
+deploy-vercel:
+	./scripts/deploy_vercel.sh

README.md

@@ -56,4 +56,11 @@ make deploy
 make stop
 make deploy-public
 make stop-public
+make deploy-vercel
 ```
+
+## Free Cloud Deploy
+
+- API: deploy `render.yaml` on Render Blueprint (free web service).
+- Web: deploy `web/` on Vercel Hobby with `NEXT_PUBLIC_API_BASE` set to the Render API URL.
+- Full steps: `docs/DEPLOYMENT.md`.

docker/server.Dockerfile

@@ -14,4 +14,4 @@ RUN pip install --no-cache-dir --upgrade pip \
     && pip install --no-cache-dir -e core -e planners -e worldmodels -e agents -e server
 
 EXPOSE 8000
-CMD ["uvicorn", "worldmodel_server.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["sh", "-c", "uvicorn worldmodel_server.main:app --host 0.0.0.0 --port ${PORT:-8000}"]

docs/DEPLOYMENT.md

@@ -1,5 +1,36 @@
 # Deployment
 
+## Recommended Free Cloud Combo: Render (API) + Vercel (Web)
+
+This project supports a fully free setup for hobby usage:
+- API on Render free web service
+- Next.js web app on Vercel Hobby
+
+### 1) Deploy API on Render
+
+1. Open [Render Dashboard](https://dashboard.render.com/).
+2. Click **New +** -> **Blueprint**.
+3. Connect this repo and deploy using `/render.yaml`.
+4. After deploy, copy your API URL (for example `https://worldmodel-gym-api.onrender.com`).
+
+Notes:
+- Render free web services can spin down when idle.
+- This repo uses sqlite in `/tmp` on Render free tier (ephemeral storage).
+
+### 2) Deploy Web on Vercel
+
+1. Open [Vercel Dashboard](https://vercel.com/new) and import this GitHub repo.
+2. Set **Root Directory** to `web`.
+3. Add environment variable:
+   - `NEXT_PUBLIC_API_BASE=https://<your-render-api-url>`
+4. Deploy.
+
+Optional CLI deploy:
+
+```bash
+make deploy-vercel
+```
+
 ## Local Production Mode
 
 Run API + web on your machine:
@@ -14,28 +45,27 @@ Stop local services:
 make stop
 ```
 
-## Public No-Card Deployment (Quick Tunnel)
+## Public No-Card Tunnel Mode
 
-This mode does not require Fly.io, cloud billing, or credit card setup.
+This mode does not require cloud accounts or credit card setup.
 It runs services locally and exposes temporary public URLs through `localtunnel`.
 
 ```bash
 make deploy-public
 ```
 
-The command will:
-- start API (`uvicorn`) on `127.0.0.1:8000`
-- create a public API tunnel URL
-- build web with `NEXT_PUBLIC_API_BASE=<public-api-url>`
-- start web on `127.0.0.1:3000`
-- create a public web tunnel URL
-
-Stop public deployment:
+Stop:
 
 ```bash
 make stop-public
 ```
 
 Notes:
-- Public tunnel URLs are ephemeral and change when restarted.
-- Keep your machine running while the public URLs are in use.
+- URLs are ephemeral and change when restarted.
+- Keep your machine running while URLs are in use.
+
+## References
+
+- Render Free tier and pricing: https://render.com/pricing
+- Render blueprint spec (`render.yaml`): https://render.com/docs/blueprint-spec
+- Vercel plans and Hobby usage: https://vercel.com/pricing

render.yaml

@@ -0,0 +1,16 @@
+services:
+  - type: web
+    name: worldmodel-gym-api
+    env: docker
+    dockerfilePath: ./docker/server.Dockerfile
+    dockerContext: .
+    plan: free
+    healthCheckPath: /healthz
+    autoDeploy: true
+    envVars:
+      - key: WMG_DB_URL
+        value: sqlite:////tmp/worldmodel_gym.db
+      - key: WMG_STORAGE_DIR
+        value: /tmp/storage
+      - key: WMG_UPLOAD_TOKEN
+        generateValue: true

scripts/deploy_vercel.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR/web"
+
+echo "Deploying web to Vercel (Hobby)."
+echo "If not logged in, this command will open interactive login."
+
+npx vercel --prod