PR Preview Environments

A full-stack preview environment per pull request. Sleeps when idle, wakes on a reviewer click.

One Dedalus Machine per open PR. The PR’s branch is checked out, dependencies installed, services running. When nobody touches the preview URL for 5 minutes the VM sleeps. When the next reviewer opens the link, it wakes in under a second with the database, seed data, and log history intact.

npm install dedalus

1. On PR opened: provision

import Dedalus from "dedalus";
const dedalus = new Dedalus({ apiKey: process.env.DEDALUS_API_KEY! });

async function waitForPreview(machineId: string, previewId: string) {
  let preview = await dedalus.machines.previews.retrieve({
    machine_id: machineId,
    preview_id: previewId,
  });
  while (preview.status === "wake_in_progress") {
    await new Promise((resolve) =>
      setTimeout(resolve, preview.retry_after_ms ?? 500),
    );
    preview = await dedalus.machines.previews.retrieve({
      machine_id: machineId,
      preview_id: previewId,
    });
  }
  if (preview.status !== "ready" || !preview.url) {
    throw new Error(preview.error_message ?? `preview ${preview.status}`);
  }
  return preview;
}

async function provisionPreview(prNumber: number, branch: string) {
  const m = await dedalus.machines.create({
    vcpu: 2,
    memory_mib: 4096,
    storage_gib: 20,
  });

  await runAndWait(m.machine_id, ["/bin/bash", "-c", `
    set -e
    apt-get update && apt-get install -y git nodejs postgresql
    git clone --depth 1 -b ${branch} https://github.com/your-org/your-app /root/app
    cd /root/app && npm install
    pg_ctlcluster 16 main start && createdb app && npm run migrate && npm run seed
    nohup npm run dev -- --host 0.0.0.0 --port 3000 >/var/log/app.log 2>&1 &
  `]);

  const preview = await dedalus.machines.previews.create({
    machine_id: m.machine_id,
    port: 3000,
    protocol: "https",
    visibility: "org",   // or "public" for external reviewers
  });
  const ready = await waitForPreview(m.machine_id, preview.preview_id);

  return { machineId: m.machine_id, url: ready.url };
}

2. On webhook hit (or middleware): wake

The simplest pattern is a small router that proxies https://pr-123.previews.your-app.com to the machine’s preview URL. Before forwarding, wake the machine.

import http from "node:http";

async function waitUntilRunning(machineId: string) {
  let machine = await dedalus.machines.wake({ machine_id: machineId });
  while (machine.status.phase !== "running") {
    if (machine.status.phase === "failed") {
      throw new Error(machine.status.reason);
    }
    await new Promise((resolve) => setTimeout(resolve, 500));
    machine = await dedalus.machines.retrieve({ machine_id: machineId });
  }
}

http.createServer(async (req, res) => {
  const prNumber = parseInt(req.headers["x-pr-number"] as string);
  const machineId = await lookupMachine(prNumber);   // your DB

  await waitUntilRunning(machineId);
  // ...then proxy req → the preview URL stored at provision time.
}).listen(8080);

wake is idempotent, but its response may still be placement_pending or starting. Queue the request until the machine reaches running, then forward it to the stored preview URL.

3. On PR merged or closed: destroy

async function teardownPreview(prNumber: number) {
  const machineId = await lookupMachine(prNumber);
  await dedalus.machines.delete({ machine_id: machineId });
}

Why a microVM beats a container here

• Postgres, Redis, real systemd, anything else that doesn’t survive container restart, just runs. Migrations + seed data persist across sleep/wake.
• Sleep means zero compute cost while the PR is dormant. A 3-week-old PR costs only the storage GiB-month — not 24/7 uptime.
• Fast resume. Queue the first request while the machine restores, then forward it normally.
• Idle auto-sleep is built in (autosleep, default "5m"). If your wake-on-traffic proxy forgets to put the VM back to sleep, the platform does it for you after five idle minutes.

Notes

• Set visibility: "public" if external collaborators need to reach the preview without a Dedalus account. Use "org" to gate it on org membership, or "private" for the creator only.
• Wake latency depends on storage size. A 20 GiB machine wakes faster than a 200 GiB one.
• Serialize cold-start traffic per machine. Queue concurrent requests behind one readiness check instead of forwarding while the machine is still starting.