کوڈنگ ایجنٹ پری ویو کے لیے VPS: ایجنٹ کی پش کی ہر برانچ کو اپنا URL

کوڈنگ ایجنٹ کہتا ہے کہ فیچر چل رہا ہے۔ شاید سچ ہو۔ اس کے لکھے ٹیسٹ پاس ہو جاتے ہیں، اور یہ اس سے کم ثابت کرتا ہے جتنا سب چاہیں گے۔ آپ اصل میں چاہتے ہیں کہ صارفین کے قریب پہنچنے سے پہلے اسے براؤزر میں کھول کر دیکھیں، اور یہ بھی ایجنٹ سے پروڈکشن چھونے کو کہے بغیر۔

پری ویو ماحول یہی حل کرتے ہیں، اور اس کے لیے کسی پلیٹ فارم کی ضرورت نہیں۔ اپنے IPv4 والا ایک VPS، Docker، Caddy اور دو مختصر اسکرپٹ ہر برانچ کو https://feature-login-form.preview.example.com جیسا اپنا URL دیتے ہیں، پاس ورڈ کے پیچھے، ہر پش پر دوبارہ بنتا ہوا۔ ایجنٹ کو ایسی SSH کلید ملتی ہے جو پری ویو شروع اور بند کر سکتی ہے، اور کچھ نہیں۔

ہم نے اسے ایک ٹیسٹ سرور پر بنایا اور لکھنے سے پہلے پورا چکر چلا کر دیکھا: بنانا، کھولنا، دوبارہ پش کرنا، ہٹانا، کلید کے غلط استعمال کی کوشش۔

کیا چاہیے

• عوامی IPv4 والا VPS۔ AI-Agent-IP پر ایک ساتھ کئی پری ویو آ جاتے ہیں۔
• ایک وائلڈ کارڈ DNS ریکارڈ: *.preview.example.com → سرور کا IP۔
• آپ کی ایپ کی ریپوزیٹری جس میں پورٹ 8080 پر سرو کرنے والی Dockerfile ہو۔ کوئی بھی زبان چلے گی۔
• apt install -y docker.io caddy git کے ساتھ Ubuntu 24.04 یا Debian 12/13۔

صرف پڑھنے والی ڈیپلائے کلید سے ریپوزیٹری ایک بار /srv/app میں کلون کر لیں۔

دو اسکرپٹ

/usr/local/bin/preview-up برانچ بنا کر آن لائن کرتی ہے:

#!/usr/bin/env bash
# preview-up <branch> — build the branch and open it at https://<name>.preview.example.com
set -euo pipefail
BRANCH="$1"
NAME=$(printf '%s' "$BRANCH" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/--*/-/g; s/^-//; s/-$//' | cut -c1-40)
DIR=/srv/previews/$NAME
git -C /srv/app fetch --quiet origin "$BRANCH"
rm -rf "$DIR"; git -C /srv/app worktree prune
git -C /srv/app worktree add --quiet --force --detach "$DIR" FETCH_HEAD
docker build --quiet -t "preview-$NAME" "$DIR" >/dev/null
docker rm -f "preview-$NAME" >/dev/null 2>&1 || true
docker run -d --name "preview-$NAME" --restart unless-stopped --memory 512m -p 127.0.0.1::8080 "preview-$NAME" >/dev/null
PORT=$(docker port "preview-$NAME" 8080/tcp | head -1 | awk -F: '{print $NF}')
cat > "/etc/caddy/previews/$NAME.caddy" <<CADDY
$NAME.preview.example.com {
	import preview_common
	reverse_proxy 127.0.0.1:$PORT
}
CADDY
systemctl reload caddy
echo "https://$NAME.preview.example.com"

/usr/local/bin/preview-down اسے ہٹاتی ہے:

#!/usr/bin/env bash
# preview-down <branch> — remove the branch preview
set -euo pipefail
NAME=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/--*/-/g; s/^-//; s/-$//' | cut -c1-40)
docker rm -f "preview-$NAME" >/dev/null 2>&1 || true
docker image rm "preview-$NAME" >/dev/null 2>&1 || true
rm -f "/etc/caddy/previews/$NAME.caddy"; rm -rf "/srv/previews/$NAME"; git -C /srv/app worktree prune
systemctl reload caddy

ان میں کچھ انتخاب سوچ سمجھ کر کیے گئے ہیں۔ کنٹینر صرف 127.0.0.1 پر رینڈم پورٹ کے ساتھ پبلش ہوتے ہیں، اس لیے Caddy کے سوا کچھ بھی ان تک نہیں پہنچتا۔ یہ اہم ہے، کیونکہ Docker کے پبلش کیے پورٹ ufw کو بائی پاس کرتے ہیں۔ ہر پری ویو پر 512 MB میموری کی حد ہے، تاکہ بے قابو ہوئی ایک برانچ باقی کو نہ گرائے۔ اور اسی برانچ کو دوبارہ چلانے پر وہ وہیں دوبارہ بن جاتی ہے: پش، up چلائیں، ری فریش۔

Caddy: ہر پری ویو کی ایک فائل، سب کے لیے ایک پاس ورڈ

mkdir -p /etc/caddy/previews /srv/previews
chmod +x /usr/local/bin/preview-up /usr/local/bin/preview-down
caddy hash-password --plaintext 'choose-a-review-password'

ہیش کو /etc/caddy/Caddyfile میں ڈالیں:

(preview_common) {
	basicauth {
		reviewer PASTE-THE-HASH-HERE
	}
}
import /etc/caddy/previews/*.caddy

پھر systemctl reload caddy۔ اب ہر پری ویو ایک ہی لاگ اِن کے پیچھے ہے، اس لیے ڈیبگ آؤٹ پٹ والی ادھوری برانچ کھلے انٹرنیٹ پر نہیں رہتی۔ نئے Caddy ورژن میں یہ ہدایت basic_auth بھی لکھی جاتی ہے؛ basicauth دونوں میں اب بھی چلتی ہے۔

ایجنٹ کی کلید: up اور down، بس

ایجنٹ کو پری ویو چالو کرنے ہیں، سرور کا مالک نہیں بننا۔ ایک deploy یوزر اور ایسی گیٹ اسکرپٹ بنائیں جو ٹھیک دو کمانڈز لے:

#!/usr/bin/env bash
# /usr/local/bin/preview-gate — the only thing the agent's key may run
set -euo pipefail
read -r ACTION BRANCH EXTRA <<< "${SSH_ORIGINAL_COMMAND:-}"
[[ -z "${EXTRA:-}" && "${BRANCH:-}" =~ ^[A-Za-z0-9][A-Za-z0-9._/-]{0,99}$ && "$BRANCH" != *..* ]] || { echo "usage: up|down <branch>" >&2; exit 2; }
case "$ACTION" in
  up)   exec sudo /usr/local/bin/preview-up "$BRANCH" ;;
  down) exec sudo /usr/local/bin/preview-down "$BRANCH" ;;
  *)    echo "usage: up|down <branch>" >&2; exit 2 ;;
esac

useradd -m -s /bin/bash deploy
echo 'deploy ALL=(root) NOPASSWD: /usr/local/bin/preview-up, /usr/local/bin/preview-down' > /etc/sudoers.d/preview
chmod 440 /etc/sudoers.d/preview && visudo -cf /etc/sudoers.d/preview
chmod 755 /usr/local/bin/preview-gate

/home/deploy/.ssh/authorized_keys میں ایجنٹ کی پبلک کلید کو اس اسکرپٹ سے باندھ دیں:

restrict,command="/usr/local/bin/preview-gate" ssh-ed25519 AAAA... coding-agent

جس مشین پر ایجنٹ کام کرتا ہے، وہاں سے:

ssh deploy@preview.example.com up feature/login-form
# https://feature-login-form.preview.example.com
ssh deploy@preview.example.com down feature/login-form

ہمارے ٹیسٹ میں up نے برانچ بنا کر پبلش کی، نئے کمٹ کے بعد دوسرے up نے نیا ورژن دکھایا، اور down نے کنٹینر اور سائٹ ہٹا دی۔ اس کلید سے cat /etc/shadow، up x; id، -x یا a/../b جیسے برانچ نام، یا انٹرایکٹو لاگ اِن کی کوشش، سب کو صرف usage: up|down <branch> ملا۔ برانچ کا نام حرف یا ہندسے سے شروع ہونا چاہیے اور اس میں .. نہیں ہو سکتا۔

ایجنٹ سے جوڑنا

Claude Code یا Codex میں پروجیکٹ کی ہدایات کی فائل میں ایک لائن کافی ہے:

برانچ پش کرنے کے بعد ssh deploy@preview.example.com up <branch> چلاؤ اور چھپا ہوا URL اپنے خلاصے میں ڈالو۔ برانچ مرج یا ترک ہو جائے تو down چلاؤ۔

اگر آپ کا CI پہلے سے ہر پش پر چلتا ہے تو وہی کمانڈ وہاں سے بلائیں اور کلید کو ایجنٹ کے ماحول سے بالکل دور رکھیں۔ یہ زیادہ سخت طریقہ ہے، اور ذاتی پروجیکٹ سے آگے کی ہر چیز کے لیے ہم یہی چنیں گے۔

کن باتوں پر نظر رکھیں

• ڈسک۔ ہر بلڈ امیج لیئر چھوڑتا ہے۔ ہفتہ وار cron سے docker image prune -f اسے قابو میں رکھتا ہے؛ down پری ویو کی اپنی امیج پہلے ہی ہٹا دیتا ہے۔
• ایسی برانچیں جنہیں کوئی بند نہیں کرتا۔ ایجنٹ انسانوں سے زیادہ برانچیں کھولتے ہیں۔ ایک ہفتے سے پرانے preview-* کنٹینرز کی فہرست بنا کر ان پر preview-down چلانے والا cron آپ کو بیس بھولے ہوئے پری ویو ملنے سے بچاتا ہے۔
• راز۔ پری ویو ٹیسٹ کریڈینشلز سے چلنے چاہئیں۔ basic auth پاس ورڈ اجنبیوں کو باہر رکھتا ہے، مگر اس سے پری ویو کو پروڈکشن ڈیٹا بیس سے جوڑنا ٹھیک نہیں ہو جاتا۔
• بلڈ کا وقت۔ امیجز سرور پر بنتی ہیں، اس لیے بھاری بلڈ چلتے پری ویو سے CPU کے لیے مقابلہ کرتا ہے۔ بلڈ میں کئی منٹ لگیں تو CI میں بنائیں اور امیج کھینچ لیں۔

ایجنٹ کا خود اس سرور پر رہنا ضروری نہیں۔ اگر رہتا ہے تو Claude Code کے لیے VPS دیکھیں، اور اسے یہ سرور خود آرڈر کرنے اور سنبھالنے دینے کے لیے اسے EQVPS MCP سرور سے جوڑیں۔ وہی مشین آپ کی ٹیم کا MCP گیٹ وے بھی ہوسٹ کر سکتی ہے۔ بغیر کسی سرور کے ناقابلِ اعتماد کوڈ چلانے کے لیے سینڈ باکس ہیں، اور اپنے IPv4 والے پلانز $8 ماہانہ سے شروع ہوتے ہیں۔