void 0.20.2 → 0.20.3

package/dist/runtime/sandbox.mjs

@@ -4,14 +4,7 @@ import { Sandbox, getSandbox as getSandbox$1 } from "@cloudflare/sandbox";
 //#region src/runtime/sandbox.ts
 const DEFAULT_SANDBOX_ID = "default";
 const DEFAULT_SANDBOX_BINDING = "SANDBOX";
-const SANDBOX_USAGE_QUEUE_BINDING = "USAGE_EVENTS_QUEUE";
-const SANDBOX_GATE_BINDING = "__VOID_PROXY";
-const HEARTBEAT_MS = 3e5;
-/**
-* Thrown by `getSandbox()` when the platform gate denies a new acquire because
-* the user has hit a concurrency or runtime budget cap. Surface this to the
-* caller so they can render a friendly error; do not retry transparently.
-*/
+const SANDBOX_SERVICE_BINDING = "__VOID_SANDBOX";
 var SandboxLimitError = class extends Error {
 	name = "SandboxLimitError";
 	reason;
@@ -20,7 +13,6 @@ var SandboxLimitError = class extends Error {
 		this.reason = reason;
 	}
 };
-/** Managed platform Sandbox is unavailable or its activation gate cannot be verified. */
 var SandboxUnavailableError = class extends Error {
 	name = "SandboxUnavailableError";
 	constructor(message = "Managed Sandbox is unavailable on this Void platform.") {
@@ -31,233 +23,102 @@ let sandboxBindingName = DEFAULT_SANDBOX_BINDING;
 function __setSandboxBindingName(bindingName) {
 	sandboxBindingName = bindingName;
 }
-const STORAGE_KEY_START_TS = "__voidStartTs";
-const STORAGE_KEY_LAST_FLUSH_TS = "__voidLastFlushTs";
-function getUsageContext() {
-	const runtimeEnv = getRawRuntimeEnv();
-	return {
-		userId: runtimeEnv.__VOID_USER_ID,
-		projectId: runtimeEnv.__PROJECT_ID,
-		slug: runtimeEnv.__VOID_PROJECT_SLUG
-	};
-}
-function getSandboxInstanceId(ctx) {
-	return ctx.id.toString();
-}
-/**
-* Flush the accumulated runtime delta to the usage queue. No-op when the
-* usage-queue binding is not bound (e.g. local dev without the platform
-* proxy). Errors are swallowed and logged — usage emission must never crash
-* the sandbox lifecycle.
-*/
-async function emitRuntimeSeconds(ctx, sandboxRuntimeSeconds) {
-	if (sandboxRuntimeSeconds <= 0) return;
-	const queue = getRawRuntimeEnv()[SANDBOX_USAGE_QUEUE_BINDING];
-	if (!queue) return;
-	const event = {
-		requests: 0,
-		responseBytes: 0,
-		sandboxRuntimeSeconds,
-		sandboxInstanceId: getSandboxInstanceId(ctx),
-		...getUsageContext()
-	};
-	try {
-		await queue.send(event);
-	} catch (error) {
-		console.error("[void/sandbox] failed to emit usage event:", error);
-	}
-}
-function isManagedPlatformSandbox(runtimeEnv) {
-	return [
-		SANDBOX_GATE_BINDING,
-		"__PROJECT_ID",
-		"__VOID_PROXY_TOKEN",
-		"__VOID_USER_ID",
-		"__VOID_PROJECT_SLUG"
-	].some((binding) => runtimeEnv[binding] !== void 0);
+function rethrowSandboxError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	for (const reason of ["concurrency", "runtime_budget"]) if (message.includes(`VOID_SANDBOX_${reason}`)) throw new SandboxLimitError(reason);
+	if (message.includes("VOID_SANDBOX_unavailable")) throw new SandboxUnavailableError();
+	throw error;
 }
-function resolveGateIdentity(runtimeEnv = getRawRuntimeEnv()) {
-	const gate = runtimeEnv[SANDBOX_GATE_BINDING];
-	if (!gate) return null;
-	const projectId = runtimeEnv.__PROJECT_ID;
-	const aiToken = runtimeEnv.__VOID_PROXY_TOKEN;
-	if (!projectId || !aiToken) return null;
-	return {
-		gate,
-		projectId,
-		aiToken
+function managedClient(capability) {
+	const call = async (target, operation, args) => {
+		try {
+			return decodeManagedResult(await target.invoke(operation, prepareManagedArgs(operation, args)));
+		} catch (error) {
+			rethrowSandboxError(error);
+		}
 	};
-}
-async function acquireManagedSandbox(sandboxId, runtimeEnv = getRawRuntimeEnv()) {
-	if (!isManagedPlatformSandbox(runtimeEnv)) return;
-	const identity = resolveGateIdentity(runtimeEnv);
-	if (!identity) throw new SandboxUnavailableError("Managed Sandbox activation could not verify the platform identity bindings.");
-	let response;
-	try {
-		response = await identity.gate.fetch("https://gate/sandbox/acquire", {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify({
-				projectId: identity.projectId,
-				aiToken: identity.aiToken,
-				sandboxId
-			})
-		});
-	} catch {
-		throw new SandboxUnavailableError("Managed Sandbox activation could not reach the platform gate.");
+	return new Proxy(Object.create(null), { get(_target, property) {
+		if (typeof property !== "string" || property === "then") return;
+		if (property === "tunnels") return new Proxy(Object.create(null), { get(_tunnels, method) {
+			if (typeof method !== "string" || method === "then") return;
+			return (...args) => call(capability, "tunnels", [method, ...args]);
+		} });
+		return (...args) => call(capability, property, args);
+	} });
+	function decodeManagedResult(value) {
+		if (Array.isArray(value)) return value.map(decodeManagedResult);
+		if (!value || typeof value !== "object") return value;
+		const record = value;
+		if (record.__voidSandboxType === "process") {
+			const { capability: processCapability, __voidSandboxType: _type, ...snapshot } = value;
+			return Object.assign(snapshot, {
+				kill: (...args) => call(processCapability, "kill", args),
+				getStatus: (...args) => call(processCapability, "getStatus", args),
+				getLogs: (...args) => call(processCapability, "getLogs", args),
+				waitForLog: (...args) => call(processCapability, "waitForLog", args),
+				waitForPort: (...args) => call(processCapability, "waitForPort", args),
+				waitForExit: (...args) => call(processCapability, "waitForExit", args)
+			});
+		}
+		if (record.__voidSandboxType === "session") {
+			const session = value;
+			return new Proxy({ id: session.id }, { get(target, property) {
+				if (property === "id") return target.id;
+				if (typeof property !== "string" || property === "then") return;
+				return (...args) => call(session.capability, property, args);
+			} });
+		}
+		return value;
 	}
-	if (response.status === 409) {
-		const body = await response.json().catch(() => ({}));
-		throw new SandboxLimitError(body.reason === "concurrency" || body.reason === "runtime_budget" ? body.reason : "concurrency");
+	function prepareManagedArgs(operation, args) {
+		if (operation !== "startProcess") return args;
+		const [command, options, ...rest] = args;
+		if (!options || typeof options !== "object" || Array.isArray(options)) return args;
+		const onStart = options.onStart;
+		if (typeof onStart !== "function") return args;
+		return [
+			command,
+			{
+				...options,
+				onStart: (process) => onStart(decodeManagedResult(process))
+			},
+			...rest
+		];
 	}
-	if (!response.ok) throw new SandboxUnavailableError(`Managed Sandbox activation was rejected by the platform gate (HTTP ${response.status}).`);
-}
-/**
-* Release notification to the gate so it can drop the active lease counter.
-* Returns the in-flight fetch as a Promise (errors swallowed) so callers can
-* route it through `ctx.waitUntil()` and keep it alive past lifecycle
-* teardown. Failure is silent — the gate maintains its own TTL fallback.
-*/
-function notifyGateRelease(ctx) {
-	const identity = resolveGateIdentity();
-	if (!identity) return Promise.resolve();
-	const sandboxId = getSandboxInstanceId(ctx);
-	return identity.gate.fetch("https://gate/sandbox/release", {
-		method: "POST",
-		headers: { "content-type": "application/json" },
-		body: JSON.stringify({
-			projectId: identity.projectId,
-			aiToken: identity.aiToken,
-			sandboxId
-		})
-	}).then(() => void 0).catch(() => {});
 }
 /**
-* Heartbeat-driven keepalive ping for the gate's concurrency slot. The DO's
-* `STALE_MS` (1h) sweep would otherwise reap slots for long-running sandbox
-* sessions whose `acquiredAt` ages past the threshold between acquire and
-* release, letting new acquires exceed `sandboxMaxConcurrentInstances`. The
-* 5 min heartbeat sits well inside the sweep window, so each successful
-* refresh resets the stale clock. Returns the in-flight fetch as a Promise
-* (errors swallowed) so callers can route it through `ctx.waitUntil()` and
-* keep the alarm path itself off the critical path — a failed refresh just
-* means the slot ages out naturally, which matches the pre-existing failure
-* mode if the gate goes down entirely.
-*/
-function notifyGateRefresh(ctx) {
-	const identity = resolveGateIdentity();
-	if (!identity) return Promise.resolve();
-	const sandboxId = getSandboxInstanceId(ctx);
-	return identity.gate.fetch("https://gate/sandbox/refresh", {
-		method: "POST",
-		headers: { "content-type": "application/json" },
-		body: JSON.stringify({
-			projectId: identity.projectId,
-			aiToken: identity.aiToken,
-			sandboxId
-		})
-	}).then(() => void 0).catch(() => {});
-}
-/**
-* Sandbox variant that participates in Void platform metering: it records
-* container runtime seconds into DO storage, emits periodic heartbeats to
-* the usage queue, and notifies the gate when the container stops.
-*
-* Generated code from `void inference` wires user `Sandbox` subclasses to
-* extend this class on platform deploys so per-tenant accounting works
-* without user opt-in. On local dev (no usage-queue / gate bindings), all
-* overrides degrade to no-ops and the sandbox behaves like the upstream
-* `Sandbox` class.
+* Retained for generated native/local Worker entries. Managed deployments host
+* the platform-owned Sandbox class in a separate Worker and never use this DO.
 */
 var VoidPlatformSandbox = class extends Sandbox {
 	async onStart() {
-		await acquireManagedSandbox(getSandboxInstanceId(this.ctx), this.env);
-		const now = Date.now();
-		const stored = await this.ctx.storage.get([STORAGE_KEY_START_TS, STORAGE_KEY_LAST_FLUSH_TS]);
-		const orphanedAnchor = stored.get(STORAGE_KEY_LAST_FLUSH_TS) ?? stored.get(STORAGE_KEY_START_TS);
-		if (orphanedAnchor !== void 0 && orphanedAnchor < now) {
-			const sandboxRuntimeSeconds = (now - orphanedAnchor) / 1e3;
-			await emitRuntimeSeconds(this.ctx, sandboxRuntimeSeconds);
-			await this.ctx.storage.delete([STORAGE_KEY_START_TS, STORAGE_KEY_LAST_FLUSH_TS]);
-		}
-		try {
-			await super.onStart();
-		} catch (err) {
-			this.ctx.waitUntil(notifyGateRelease(this.ctx));
-			throw err;
-		}
-		const startedAt = Date.now();
-		await this.ctx.storage.put({
-			[STORAGE_KEY_START_TS]: startedAt,
-			[STORAGE_KEY_LAST_FLUSH_TS]: startedAt
-		});
-		await this.ctx.storage.setAlarm(startedAt + HEARTBEAT_MS);
-	}
-	async alarm(alarmProps) {
-		await super.alarm(alarmProps);
-		const lastFlush = await this.ctx.storage.get(STORAGE_KEY_LAST_FLUSH_TS);
-		if (typeof lastFlush !== "number") return;
-		const now = Date.now();
-		const sandboxRuntimeSeconds = Math.max(0, (now - lastFlush) / 1e3);
-		await emitRuntimeSeconds(this.ctx, sandboxRuntimeSeconds);
-		this.ctx.waitUntil(notifyGateRefresh(this.ctx));
-		await Promise.all([this.ctx.storage.put(STORAGE_KEY_LAST_FLUSH_TS, now), this.ctx.storage.setAlarm(now + HEARTBEAT_MS)]);
-	}
-	async onStop() {
-		await this.flushFinal();
-		this.ctx.waitUntil(notifyGateRelease(this.ctx));
-		await super.onStop();
-	}
-	async onActivityExpired() {
-		await this.flushFinal();
-		this.ctx.waitUntil(notifyGateRelease(this.ctx));
-		await super.onActivityExpired();
-	}
-	async flushFinal() {
-		const lastFlush = await this.ctx.storage.get(STORAGE_KEY_LAST_FLUSH_TS);
-		if (typeof lastFlush === "number") {
-			const sandboxRuntimeSeconds = Math.max(0, (Date.now() - lastFlush) / 1e3);
-			await emitRuntimeSeconds(this.ctx, sandboxRuntimeSeconds);
-		}
-		await this.ctx.storage.delete(STORAGE_KEY_START_TS);
-		await this.ctx.storage.delete(STORAGE_KEY_LAST_FLUSH_TS);
+		const env = this.env;
+		if (env.__PROJECT_ID !== void 0 || env.__VOID_PROXY !== void 0) throw new SandboxUnavailableError("Managed Sandboxes require the platform Sandbox controller. Redeploy this application.");
+		await super.onStart();
 	}
 };
-/**
-* Resolve the platform-provided sandbox stub for the given id, optionally
-* coordinating with the platform gate to enforce per-user concurrency and
-* runtime budgets.
-*
-* When the gate binding (`__VOID_PROXY` by default) is present AND the
-* platform's `__PROJECT_ID` + `__VOID_PROXY_TOKEN` identity vars are
-* available, we POST to `https://gate/sandbox/acquire` with the HMAC-signed
-* body the shared proxy auth middleware expects. A `409` response means the
-* user has exceeded a budget — we throw `SandboxLimitError` so the caller
-* can render a clear message. Any other non-OK status (or a thrown transport
-* error from the service binding) fails closed before returning a usable
-* managed stub.
-*
-* When all reserved platform identity bindings are absent, this is a native
-* Cloudflare or local deployment and returns the upstream stub directly.
-*
-* The stub is constructed BEFORE calling the gate so we can pass its opaque,
-* namespace-specific Durable Object id (`stub.id.toString()`) as `sandboxId`.
-* The same id is available as `ctx.id.toString()` inside lifecycle hooks, so
-* acquire, heartbeat, and release use one globally unique instance identity
-* even when separate projects or deployments both request the name `default`.
-* Constructing the stub does NOT start a container — that only happens on
-* the first method call against the stub.
-*/
+/** Resolve an isolated Sandbox on the current deployment. Starts on first use. */
 async function getSandbox(id = DEFAULT_SANDBOX_ID, options) {
 	const { binding = sandboxBindingName, ...sandboxOptions } = options ?? {};
-	const namespace = requireRuntimeBinding(binding);
-	const stub = getSandbox$1(namespace, id, {
+	const runtimeEnv = getRawRuntimeEnv();
+	const service = runtimeEnv[SANDBOX_SERVICE_BINDING];
+	if (service) {
+		if (binding !== sandboxBindingName) throw new SandboxUnavailableError(`Managed Sandbox binding ${binding} is unavailable.`);
+		try {
+			return managedClient(await service.getSandbox(id, {
+				normalizeId: true,
+				...sandboxOptions
+			}));
+		} catch (error) {
+			rethrowSandboxError(error);
+		}
+	}
+	if (runtimeEnv.__PROJECT_ID !== void 0 || runtimeEnv.__VOID_PROXY !== void 0) throw new SandboxUnavailableError("This deployment has no managed Sandbox controller. Redeploy this application.");
+	return getSandbox$1(requireRuntimeBinding(binding), id, {
 		normalizeId: true,
 		...sandboxOptions
 	});
-	await acquireManagedSandbox(stub.id.toString());
-	return stub;
 }
 const sandbox = { get: getSandbox };
 //#endregion
-export { DEFAULT_SANDBOX_BINDING, DEFAULT_SANDBOX_ID, HEARTBEAT_MS, SANDBOX_GATE_BINDING, SANDBOX_USAGE_QUEUE_BINDING, Sandbox, SandboxLimitError, SandboxUnavailableError, VoidPlatformSandbox, __setSandboxBindingName, getSandbox, sandbox };
+export { DEFAULT_SANDBOX_BINDING, DEFAULT_SANDBOX_ID, SANDBOX_SERVICE_BINDING, Sandbox, SandboxLimitError, SandboxUnavailableError, VoidPlatformSandbox, __setSandboxBindingName, getSandbox, sandbox };

package/dist/{secret-Bzzi2e9E.mjs → secret-AcPi-FoA.mjs}

@@ -1,7 +1,7 @@
 import { A as outro, C as cancel, D as log, E as intro, I as isCancel, j as password, k as note, r as cliTitle, w as confirm } from "./output-B0cfNSx5.mjs";
 import { S as readProjectConfig, l as getToken, x as readDeploymentPlatform } from "./auth-DPl6kck4.mjs";
 import { m as validateSecretValues } from "./env-validation-CF6KvTRf.mjs";
-import { n as PlatformClient } from "./client-dHfSJvAN.mjs";
+import { n as PlatformClient } from "./client-BQBrZoCX.mjs";
 import { r as resolveProjectBySlug, t as getRequestedProjectSlug } from "./resolve-project--Vxawf7z.mjs";
 import { readFileSync } from "node:fs";
 //#region src/cli/secret.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "void",
-  "version": "0.20.2",
+  "version": "0.20.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -318,11 +318,11 @@
     "@cloudflare/vite-plugin": "1.54.7",
     "@cloudflare/workers-types": "^4.20260702.1",
     "@napi-rs/keyring": "2.0.0",
-    "@void/deploy-cloudflare": "0.20.2",
-    "@void/deploy-core": "0.20.2",
-    "@void/edge": "0.20.2",
-    "@void/isr": "0.20.2",
-    "@void/platform": "0.20.2",
+    "@void/deploy-cloudflare": "0.20.3",
+    "@void/deploy-core": "0.20.3",
+    "@void/edge": "0.20.3",
+    "@void/isr": "0.20.3",
+    "@void/platform": "0.20.3",
     "better-auth": "^1.7.3",
     "better-sqlite3": "^13.0.3",
     "blake3-jit": "^1.1.0",
@@ -368,7 +368,7 @@
     "zod": "^4.6.1"
   },
   "peerDependencies": {
-    "@void/md": "0.20.2",
+    "@void/md": "0.20.3",
     "arktype": ">=2.0.0",
     "valibot": ">=1.0.0-beta.7",
     "vite": "^8.0.0",

package/skills/void/SKILL.md

@@ -23,7 +23,7 @@ read permission; `void platform install --plan` verifies coverage. Use the
 self-hosted platform guide for certificate setup rather than enabling a paid
 product without an explicit request.
 
-For first-time platform setup, follow `docs/guide/self-hosted-platform.md` in order and introduce credentials when the user reaches that step. Recommend a domain; offer explicit `void platform install --workers-dev` for testing before one is ready. PostgreSQL, credentials for the selected login methods, runtime/R2 credentials, and saved signing/encryption keys are required. GitHub is the default and is optional. `--auth-config` accepts nonsecret provider configuration with environment secret references; `--plan` does not read those secrets. Configurable installations finish first-administrator setup using a one-time code and browser identity confirmation. Domain-free installation skips zone/DNS/certificate operations and can use browser login. `void platform domain set <domain>` later performs resumable DNS/HTTPS setup while preserving existing test URLs and the API origin. The command checks the deployed runtime token's cache-purge permission for the new zone; it does not ask users to retrieve that token. Prefer interactive prompts for secrets and keep CI variables in the CI workflow. Void creates the platform infrastructure and database tables.
+For first-time platform setup, follow the installation pages linked from `docs/guide/self-hosted-platform.md` in order and introduce credentials when the user reaches that step. Recommend a domain; offer explicit `void platform install --workers-dev` for testing before one is ready. PostgreSQL, credentials for the selected login methods, runtime/R2 credentials, and saved signing/encryption keys are required. GitHub is the default and is optional. `--auth-config` accepts nonsecret provider configuration with environment secret references; `--plan` does not read those secrets. Configurable installations finish first-administrator setup using a one-time code and browser identity confirmation. Domain-free installation skips zone/DNS/certificate operations and can use browser login. `void platform domain set <domain>` later performs resumable DNS/HTTPS setup while preserving existing test URLs and the API origin. The command checks the deployed runtime token's cache-purge permission for the new zone; it does not ask users to retrieve that token. Prefer interactive prompts for secrets and keep CI variables in the CI workflow. Void creates the platform infrastructure and database tables.
 
 For an existing Cloudflare site, run `void deploy` with its root `wrangler.jsonc` or `wrangler.json`. An unlinked project gets a prompt to link and deploy using the existing Worker and resources. Accepting verifies and saves the destination, then continues deployment. Keep new application resources, migrations, auth setup, and secret changes separate from this first handoff; ISR has its own explicit cache choice. The active Worker Version must be the latest upload so inherited secrets have an unambiguous source. Failed builds retain the link for retry. Read `docs/integrations/cloudflare.md` for the supported configuration and rollback behavior.
 
@@ -91,7 +91,7 @@ Cloudflare browser login does not grant AI Gateway access. A platform installati
 
 Use `--runtime <directory>` on platform install, upgrade, repair, enable, or rollback when deploying a locally built `@void/platform` runtime. The directory must contain the generated integrity manifest, Worker artifacts, and migration tree. Build it with `vp run --filter @void/platform build`; Git source revisions are detected automatically, with `-dirty` for uncommitted changes. `VOID_PLATFORM_SOURCE_REVISION` is an optional override. Do not treat this as a safety bypass: custom and packaged runtimes follow the same verification and rollback path.
 
-For self-hosted platform installation, require a dedicated empty PostgreSQL database. Interactive lifecycle commands use Cloudflare browser OAuth with keyring storage. Wrangler OAuth has Zone Read, so a plan that creates a zone or DNS record requires a scoped `CLOUDFLARE_API_TOKEN` with Account → Zone → Edit and/or Zone → DNS → Edit; finish Workers onboarding and choose a workers.dev subdomain for a fresh Cloudflare account. The installed platform uses a separate `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`. Its core permissions include Hyperdrive: Write at account scope and Cache Purge: Purge on the application zone; SSL and Certificates: Edit is needed only when a custom runtime enables custom project domains. The installer preflights account and Hyperdrive access and safely verifies Cache Purge for an existing zone with a unique nonexistent URL. Fresh installs require unique per-installation values from the operator's secret manager: `VOID_PLATFORM_JWT_SECRET` with at least 32 random bytes and `VOID_PLATFORM_PROJECT_SECRET_KEY` as canonical base64 for 32 random bytes. Never let a local checkpoint or ephemeral CI runner be their only custodian. Enabling email generates a separate signing key in encrypted recovery state; supply `VOID_PLATFORM_EMAIL_SIGNING_SECRET` from the secret manager for headless installs without persistent recovery files. The installer transactionally claims the database for one installation, pins that URL after a successful claim, never removes the claim during uninstall, and uses it for a cross-host lifecycle lock plus a secret-free authoritative lifecycle manifest. Local recovery checkpoints are AES-256-GCM encrypted with an OS-keychain key; never place platform secrets in plaintext files. After discovery on a new machine, provide `VOID_PLATFORM_DATABASE_URL`. For email-enabled installations without encrypted recovery state, also restore the original `VOID_PLATFORM_EMAIL_SIGNING_SECRET`; recreating only the email gateway needs this key, not JWT or runtime credentials. Normal upgrades preserve other deployed Worker secrets; restore the original runtime, GitHub, R2, JWT, and project-encryption values when recreating the API or proxy as documented. Managed platform Sandbox is paused for removal: preview `void platform system sandbox-drain --plan`, follow each returned `nextCursor` with `--cursor '<value>'` to inspect bounded pages, then apply with `--yes` and rerun until the DB-backed response reports `complete: true`; never delete an unverified app by name. The installer trusts only DB-backed sandbox-drain probe protocol v1. Before it accepts an empty inventory, the database admission barrier makes older deployment inserts finish and become visible or rejects them after the protocol floor is armed. Lifecycle redeploys preserve unmanaged Worker routes and custom domains in both the new trigger state and rollback snapshot. They stop before migrations or uploads when live Hyperdrive origin metadata differs from the pinned database. Platform upgrade SQL is forward-only: packaged hashes and the live Drizzle prefix must match, pending migrations require an exact source-version/schema rollback edge, and the old version remains authoritative until target health succeeds. Use `void platform rollback --runtime <earlier>` only when the installed runtime declares the exact earlier version/schema compatible; pass `--from-runtime` for the exact current custom artifact. Rollback preserves the forward database schema and cannot lower a database-required safety protocol. Safe uninstall retains Worker routes, custom domains, and R2 for explicit manual cleanup because Cloudflare cannot condition their deletion on an immutable generation.
+For self-hosted platform installation, require a dedicated empty PostgreSQL database. Interactive lifecycle commands use Cloudflare browser OAuth with keyring storage. Wrangler OAuth has Zone Read, so a plan that creates a zone or DNS record requires a scoped `CLOUDFLARE_API_TOKEN` with Account → Zone → Edit and/or Zone → DNS → Edit; finish Workers onboarding and choose a workers.dev subdomain for a fresh Cloudflare account. The installed platform uses a separate `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`. Its core permissions include Hyperdrive: Write at account scope and Cache Purge: Purge on the application zone; SSL and Certificates: Edit is needed only when a custom runtime enables custom project domains. Managed Sandbox apps additionally require Workers Paid plus Account → Containers → Edit and Account → Cloudchamber → Edit on that runtime token; these are checked on the first Sandbox application deploy, not during platform install or upgrade. The installer preflights account and Hyperdrive access and safely verifies Cache Purge for an existing zone with a unique nonexistent URL. Fresh installs require unique per-installation values from the operator's secret manager: `VOID_PLATFORM_JWT_SECRET` with at least 32 random bytes and `VOID_PLATFORM_PROJECT_SECRET_KEY` as canonical base64 for 32 random bytes. Never let a local checkpoint or ephemeral CI runner be their only custodian. Enabling email generates a separate signing key in encrypted recovery state; supply `VOID_PLATFORM_EMAIL_SIGNING_SECRET` from the secret manager for headless installs without persistent recovery files. The installer transactionally claims the database for one installation, pins that URL after a successful claim, never removes the claim during uninstall, and uses it for a cross-host lifecycle lock plus a secret-free authoritative lifecycle manifest. Local recovery checkpoints are AES-256-GCM encrypted with an OS-keychain key; never place platform secrets in plaintext files. After discovery on a new machine, provide `VOID_PLATFORM_DATABASE_URL`. For email-enabled installations without encrypted recovery state, also restore the original `VOID_PLATFORM_EMAIL_SIGNING_SECRET`; recreating only the email gateway needs this key, not JWT or runtime credentials. Normal upgrades preserve other deployed Worker secrets; restore the original runtime, GitHub, R2, JWT, and project-encryption values when recreating the API or proxy as documented. Upgrades enable managed Sandboxes automatically. An upgrade from the tenant-owned legacy may still require `void platform system sandbox-drain`: preview with `--plan`, follow each `nextCursor`, then apply with `--yes` until the DB-backed response reports `complete: true`; never delete an unverified app by name. The installer trusts only DB-backed sandbox-drain probe protocol v1. Before it accepts an empty inventory, the database admission barrier makes older deployment inserts finish and become visible or rejects them after the protocol floor is armed. Lifecycle redeploys preserve unmanaged Worker routes and custom domains in both the new trigger state and rollback snapshot. They stop before migrations or uploads when live Hyperdrive origin metadata differs from the pinned database. Platform upgrade SQL is forward-only: packaged hashes and the live Drizzle prefix must match, pending migrations require an exact source-version/schema rollback edge, and the old version remains authoritative until target health succeeds. Use `void platform rollback --runtime <earlier>` only when the installed runtime declares the exact earlier version/schema compatible; pass `--from-runtime` for the exact current custom artifact. Rollback preserves the forward database schema and cannot lower a database-required safety protocol. Safe uninstall retains Worker routes, custom domains, and R2 for explicit manual cleanup because Cloudflare cannot condition their deletion on an immutable generation.
 
 For self-hosted recovery, `VOID_PLATFORM_PROJECT_SECRET_KEY` restores an original `v1` project-secret keyring. After rotation, restore every retained version with `VOID_PLATFORM_PROJECT_SECRET_KEYS_JSON` and its active entry with `VOID_PLATFORM_PROJECT_SECRET_ACTIVE_KEY_VERSION`. These inputs restore a missing API Worker and never replace the live keyring of an existing Worker. Inject them from a secret manager without logging them or writing plaintext files.
 

package/skills/void/docs/guide/deployment.md

@@ -14,23 +14,23 @@ Direct Cloudflare deployment runs an application in your account. A self-hosted
 Void platform provides that deployment service to a team using the operator's
 account. Both use the same application APIs, with the following differences:
 
-| Feature                                          | Direct Cloudflare                | Core self-hosted platform                 |
-| ------------------------------------------------ | -------------------------------- | ----------------------------------------- |
-| Static sites, SPAs, and native Pages SSR         | Supported                        | Supported                                 |
-| Routing rules, WebSockets, queues, cron, and ISR | Supported                        | Supported                                 |
-| D1, KV, R2, and external SQL through Hyperdrive  | Supported                        | Supported                                 |
-| Workers AI and provider requests                 | Your account and gateway         | Installation gateway and proxy            |
-| Runtime logs                                     | Live Cloudflare tail             | Retained platform logs                    |
-| Application rollback                             | Worker versions                  | Retained platform deployments             |
-| Typed Durable State                              | Supported                        | Unavailable                               |
-| Sandboxes                                        | Requires Workers Paid and Docker | Unavailable in beta                       |
-| Custom application domains                       | Supported                        | Unavailable in the core installation      |
-| Generated GitHub deployment workflow             | Supported                        | Use your CI with a scoped developer token |
-| User dashboard and managed GitHub builds         | Not required                     | Not included in a standard installation   |
+| Feature                                          | Direct Cloudflare                | Core self-hosted platform                     |
+| ------------------------------------------------ | -------------------------------- | --------------------------------------------- |
+| Static sites, SPAs, and native Pages SSR         | Supported                        | Supported                                     |
+| Routing rules, WebSockets, queues, cron, and ISR | Supported                        | Supported                                     |
+| D1, KV, R2, and external SQL through Hyperdrive  | Supported                        | Supported                                     |
+| Workers AI and provider requests                 | Your account and gateway         | Installation gateway and proxy                |
+| Runtime logs                                     | Live Cloudflare tail             | Retained platform logs                        |
+| Application rollback                             | Worker versions                  | Retained platform deployments                 |
+| Typed Durable State                              | Supported                        | Unavailable                                   |
+| Sandboxes                                        | Requires Workers Paid and Docker | Requires Workers Paid on the platform account |
+| Custom application domains                       | Supported                        | Unavailable in the core installation          |
+| Generated GitHub deployment workflow             | Supported                        | Use your CI with a scoped developer token     |
+| User dashboard and managed GitHub builds         | Not required                     | Not included in a standard installation       |
 
 Ordinary native applications remain compatible with Workers Free within its
 quotas. Installing a team platform requires Workers for Platforms and the
-[documented infrastructure](./self-hosted-platform.md#cloudflare-footprint).
+[documented infrastructure](./platform/installation/domains.md#cloudflare-footprint).
 Application rollback never reverses database migrations.
 
 Routing-rule parity applies to native Void applications and static deployments.

package/skills/void/docs/guide/email.md

@@ -10,7 +10,7 @@ Send transactional email from your app via [Cloudflare's `send_email` binding](h
 import { sendEmail } from 'void/email';
 
 const result = await sendEmail({
-  from: 'Acme <acme+noreply@mail.void.cloud>',
+  from: 'Acme <acme+noreply@mail.example.com>', // use your project's sender address
   to: 'user@example.com',
   subject: 'Welcome',
   text: 'Thanks for signing up!',
@@ -36,9 +36,13 @@ hits first, because a recipient you have not verified yet fails per-recipient.
 
 ## Setup
 
-Zero config on the Void platform (`void deploy`). Every Void project ships with:
+On a platform with email enabled, your app needs no email configuration before
+`void deploy`. Ask your administrator for the platform's shared mail domain. A
+self-hosted administrator [enables email during installation or upgrade](/guide/platform/installation/credentials#runtime-token-permissions); installations without it do not offer platform email. Void Cloud uses `mail.void.cloud`.
 
-- **Sender** — `<your-slug>+noreply@mail.void.cloud`. Used as the default `from` if you omit it. The platform owns the zone with Email Routing + DKIM + SPF + DMARC set up; you do nothing. Project slugs are capped at 56 characters so this local part fits RFC 5321's 64 octets; a project created before the cap with a longer slug must pass `from` explicitly.
+Each project on an email-enabled platform has:
+
+- **Sender** — `<your-slug>+noreply@<mail-domain>`. Used as the default `from` if you omit it. The platform administrator configures the mail zone and its Email Routing, DKIM, SPF, and DMARC records. Project slugs are capped at 56 characters so this local part fits RFC 5321's 64 octets; a project created before the cap with a longer slug must pass `from` explicitly.
 - **No worker binding to add** — outbound mail is sent by the Void proxy, which holds the
   platform `send_email` binding. Your worker never gets one, so there is nothing to configure.
 - **Your own address as a recipient** — the email on your Void account is registered as a recipient when the project is created. It is verified at once when Cloudflare already holds it verified for the platform (you clicked its link for an earlier project of yours); otherwise Cloudflare mails it a verification link, and until you click that link and run `void email destinations` — the listing is what records the click — a send to yourself comes back `ok: false` with a per-recipient `UNVERIFIED_DESTINATION` in `result.deliveries`.
@@ -61,7 +65,7 @@ Cloudflare emails the recipient with a verification link. Once they click it and
 void email destinations
 ```
 
-The project owner's email (the GitHub address you signed up with) is added automatically when the project is created, so it skips `void email allow` — not the verification. See [Setup](#setup) for when it is verified at once and when there is a link to click.
+The project owner's account email is added automatically when the project is created on an email-enabled platform, so it skips `void email allow` — not the verification. See [Setup](#setup) for when it is verified at once and when there is a link to click.
 
 ::: warning When this is the right fit
 The shared sender is great for: ops alerts to the team, notifications to the project owner, reply-by-email flows on top of inbound, internal/app-internal mail.
@@ -71,7 +75,7 @@ For SaaS sending to arbitrary end-users (every signup gets a welcome email), the
 
 ## Your own domain on the platform
 
-The shared sender lives on the platform's `mail.void.cloud` zone. To send — and receive — at a domain you own, register its Cloudflare zone with the project:
+The shared sender uses the platform's configured mail domain. To send — and receive — at a domain you own, register its Cloudflare zone with the project:
 
 ```sh
 void email domain add acme.com
@@ -120,7 +124,7 @@ At most 50 recipients across `to`, `cc` and `bcc` per call. Each address is chec
 
 `Address` accepts either a string (`"hello@acme.dev"` or `"Name <hello@acme.dev>"`) or an object (`{ email, name? }`). Display names with non-ASCII characters are RFC 2047 encoded automatically.
 
-On the platform the sender is pinned to your project. `from` must be your project's own platform address — `<project-slug>@mail.void.cloud` or `<project-slug>+<tag>@mail.void.cloud`, optionally with a display name (`Acme <acme+noreply@mail.void.cloud>`) — or any address on a domain registered with `void email domain add` (see [Your own domain on the platform](#your-own-domain-on-the-platform)). Anything else is rejected with `INVALID_FROM`. Omit `from` and Void fills in `<project-slug>+noreply@mail.void.cloud` for you.
+On the platform the sender is pinned to your project. `from` must be your project's own platform address — `<project-slug>@<mail-domain>` or `<project-slug>+<tag>@<mail-domain>`, optionally with a display name — or any address on a domain registered with `void email domain add` (see [Your own domain on the platform](#your-own-domain-on-the-platform)). For example, if your platform's mail domain is `mail.example.com`, you can use `Acme <acme+noreply@mail.example.com>`. Anything else is rejected with `INVALID_FROM`. Omit `from` and Void fills in `<project-slug>+noreply@<mail-domain>` for you.
 
 On your own Cloudflare account, `from` defaults to `email.from` from `void.json` and must be on a domain your account can send from; Cloudflare rejects any other sender and `sendEmail` reports it as `INVALID_FROM`.
 
@@ -128,7 +132,6 @@ On your own Cloudflare account, `from` defaults to `email.from` from `void.json`
 
 ```ts
 await sendEmail({
-  from: 'Acme <acme+noreply@mail.void.cloud>',
   to: 'user@example.com',
   subject: 'Your receipt',
   text: 'Receipt attached.',
@@ -146,7 +149,6 @@ For inline images (e.g. logos referenced from HTML), set `disposition: 'inline'`
 
 ```ts
 await sendEmail({
-  from: 'Acme <acme+noreply@mail.void.cloud>',
   to: 'user@example.com',
   subject: 'Hello',
   html: '<img src="cid:logo" alt="Acme">',
@@ -241,7 +243,7 @@ The dev inbox is **not** available under a Class B or C framework — SvelteKit,
 
 ```ts
 const result = await sendEmail({
-  from: 'acme+noreply@mail.void.cloud',
+  from: 'acme+noreply@mail.example.com', // replace with your project sender
   to: 'verified@acme.dev',
   subject: 'Skips the dev inbox',
   text: 'Not captured — and not delivered either.',
@@ -264,7 +266,7 @@ describe('signup flow', () => {
     const inbox = createEmailTestHarness();
 
     await sendEmail({
-      from: 'acme+noreply@mail.void.cloud',
+      from: 'acme+noreply@mail.example.com', // use your project sender
       to: 'user@example.com',
       subject: 'Welcome',
       text: 'Hi!',