void 0.21.9 → 0.22.0

package/skills/void/docs/guide/platform/administration/zero-trust.md

@@ -0,0 +1,318 @@
+---
+outline: deep
+---
+
+# Project Zero Trust
+
+Project Zero Trust puts Cloudflare Access in front of the hostnames of projects deployed to your platform, including custom domains. Visitors sign in with one of your identity providers before they reach a protected project. Each project can still be made public.
+
+This is separate from the Access login and protection for the platform API. Projects deployed directly to Cloudflare are not affected.
+
+The steps below set it up. [How Protection Works](#how-protection-works) explains what visitors see, which Access applications Void creates, and what happens while settings change.
+
+## Requirements
+
+- A Cloudflare Zero Trust organization in the account that hosts the platform, with the identity providers and reusable Access policies you want to use. Select at least one Allow policy that matches people by identity. Void rejects Bypass and Service Auth policies, and rules that allow Everyone or any service token.
+- A Cloudflare API token for that account with **Access: Apps and Policies Write** and **Access: Organizations, Identity Providers, and Groups Read**. Void keeps it separate from the platform runtime token, stores it encrypted, and never shows it again.
+- Free Access applications in the account. Cloudflare's default limit is 500 per account. Count the applications you already manage outside Void, then add the ones Void needs, as described in [Access Applications Void Creates](#access-applications-void-creates).
+- Platform API, proxy, and email gateway hostnames outside the project application domain. Configuration is rejected when project protection would cover one of them. Any other hostname under the project application domain also asks for sign-in, except the `/health` path of `void-platform-health.<your domain>`, which Void keeps open for its health checks and never serves from a project. New projects cannot use that name. A project that already uses it keeps every other path, protected or public like any other project.
+
+## Enable Zero Trust
+
+Open **Zero Trust** in the administrator UI, or use the operator CLI:
+
+```sh
+printf '%s' "$ACCESS_API_TOKEN" | void platform zero-trust configure \
+  --identity-providers <id[,id...]> \
+  --policies <id[,id...]> \
+  --existing-projects public \
+  --protect-new-projects \
+  --token-stdin \
+  --yes
+```
+
+- `--existing-projects protected|public` decides what happens to the projects that already exist. It is required when you enable Zero Trust.
+- `--protect-new-projects` protects projects created from now on. Omit it to make new projects public.
+- Use `--plan` instead of `--yes` to check the change without applying it.
+
+To change the identity providers, policies, token, or new-project default later, run the same command without `--existing-projects`. Existing projects keep their protection; use the project overrides below to change one project.
+
+## Check Status
+
+```sh
+void platform zero-trust status
+void platform zero-trust status --check
+```
+
+`status` shows the saved settings, the current operation, and how many projects are protected, public, or waiting. `--check` also compares the settings with Cloudflare Access. In the administrator UI, use **Check with Cloudflare**.
+
+## Project Overrides
+
+Project owners and project administrators can protect a project or make it public. Readers can see its state.
+
+```sh
+void project zero-trust status
+void project zero-trust protect
+void project zero-trust public
+void project zero-trust reconcile
+```
+
+`status` also tells you whether protection can be changed right now. Making a project public does not change the default for new projects.
+
+Installation administrators can do the same from the project page in the administrator UI or with `void platform zero-trust project-status|project-protect|project-public|project-reconcile <project-id>`.
+
+Deploys and rollbacks wait until a project's protection change is finished. If one is refused, run `void project zero-trust status` to see why; the owner or a project administrator can run `void project zero-trust reconcile` before you try again. A protected project can have up to 100 custom domains.
+
+## Disable Zero Trust
+
+```sh
+void platform zero-trust disable
+```
+
+This removes the Access applications Void created and makes all projects public. On large installations it runs in steps; run it again, or check `void platform zero-trust status`, until Zero Trust shows as disabled with no operation running.
+
+Uninstalling the platform does not remove these applications. `void platform uninstall` refuses to start while Zero Trust is enabled, a change is still running, or some Void-managed Access applications are left. Its error lists their names. Disable Zero Trust first, then uninstall. Once the uninstall starts turning the platform off, Zero Trust changes and deployments are refused. If it stops after that point, run it again, or bring the platform back with `void platform enable` or `void platform repair`. If a project's applications could not be removed, Void retries every hour while the platform is enabled. If the error says a project deletion stopped partway, run `void project delete` for that project again to remove them.
+
+## How Protection Works
+
+Every request to a protected project passes two checks before your code runs:
+
+```text
+Visitor
+  │
+  ▼
+Cloudflare Access ─── not signed in ─────────▶ sign-in page
+  │ signed in and allowed by your policies
+  ▼
+Void checks the Access token ─── rejected ───▶ 403 page
+  │ token is valid for this hostname
+  ▼
+Your project: routes, pages, assets, WebSockets
+```
+
+A public project skips both. Access lets every visitor through, and Void does not look for a token.
+
+### What Visitors See
+
+A protected project asks visitors to sign in with one of the identity providers you selected. If you selected exactly one, visitors go straight to it. Otherwise, they pick one of the selected providers. A sign-in lasts 12 hours. After that, Access asks again.
+
+Protection follows the project to every hostname it answers on:
+
+| Hostname                                  | Protected project | Public project |
+| ----------------------------------------- | ----------------- | -------------- |
+| `<slug>.<your domain>`                    | Sign-in required  | Open to anyone |
+| The project's `workers.dev` testing URL   | Sign-in required  | Open to anyone |
+| Custom domains, such as `app.example.com` | Sign-in required  | Open to anyone |
+
+Void only covers the `workers.dev` testing URLs of this installation. Other Workers in the account are not affected. On an installation without a domain, the `workers.dev` testing URL is the only project URL, and the shared project application covers only those URLs.
+
+#### The 403 Page
+
+Void answers `403 Cloudflare Access authentication required` when a request reaches a protected project without a valid Access token for it. Page requests get a short HTML error page. Requests under `/api`, requests for files, requests that are not `GET` or `HEAD`, and requests that do not accept HTML get the same message as plain text. The response is never cached.
+
+Visitors who went through the sign-in page normally never see it. They can see it:
+
+- for a short time while the project is switching between protected and public;
+- while a Zero Trust change is still being applied to the project;
+- when a Void-managed Access application was deleted, or its hostnames were changed, in the Cloudflare dashboard. See [Editing Applications in the Dashboard](#editing-applications-in-the-dashboard).
+
+#### Every Path Is Covered
+
+Protection applies to the whole hostname. There are no path exceptions. `/api/*` routes, static files, hashed assets, `robots.txt`, `favicon.ico`, server-sent events, and WebSockets all require a signed-in visitor.
+
+#### Webhooks and Other Non-Browser Clients
+
+Void only accepts policies that match people by identity. It rejects Bypass and Service Auth policies, and rules that allow Everyone or any service token. So a machine cannot pass on its own. Payment and Git webhooks, CI jobs, uptime checks, and plain `curl` calls get the sign-in page or the 403 response.
+
+If a project must accept such requests:
+
+- make the project public with `void project zero-trust public` and check callers in your own code, or
+- move the endpoints that machines call into a separate project, and make only that project public.
+
+### Two Checks on Every Request
+
+Cloudflare Access is the first check. It runs at Cloudflare's edge, shows the sign-in page, and applies your policies. Only visitors your policies allow get an Access token for the project.
+
+Void is the second check. Before a protected project runs, Void confirms that the request carries an Access token that:
+
+- was issued by your Zero Trust team;
+- belongs to one of the Access applications Void created for this project's hostname;
+- has not expired.
+
+If any of this fails, the visitor gets the [403 page](#the-403-page). Your routes, assets, and caches are never reached.
+
+This gives you one guarantee: **deleting a Void-managed Access application, or changing its hostnames, cannot make a protected project public.** If someone deletes Void's application, or points it at other hostnames, visitors are refused instead of let in. Loosening the policies of Void's application in the dashboard does widen who can sign in, until the next update puts Void's policies back.
+
+The second check does not look at your policies again. Who may sign in is decided only by the policies in Cloudflare Access. If you loosen a selected policy, the change applies to every protected project.
+
+### Access Applications Void Creates
+
+Void creates and owns these self-hosted applications in your Zero Trust organization:
+
+| Application                | Covers                                                                    | Policy                                                           | Exists                                                             |
+| -------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Shared project application | `*.<your domain>` and this installation's `workers.dev` testing URLs      | Your selected policies and identity providers                    | Once, while Zero Trust is enabled                                  |
+| Public exception           | One public project's `<slug>.<your domain>` and `workers.dev` testing URL | A Bypass policy for Everyone, named `Void project is public`     | One for each public project                                        |
+| Custom domain application  | All custom domains of one protected project                               | Your selected policies and identity providers                    | One for each protected project that has custom domains             |
+| Health check exception     | `void-platform-health.<your domain>/health`                               | A Bypass policy for Everyone, named `Void platform health check` | Once, while Zero Trust is enabled on an installation with a domain |
+
+Custom domains of a public project need no Access application.
+
+The number of applications Void needs is:
+
+```text
+2 + public projects + protected projects that have custom domains
+```
+
+Use 1 instead of 2 on an installation without a domain. For example, 40 projects with 10 public and 5 protected projects that have custom domains need 2 + 10 + 5 = 17 applications. Void stops with an error when the account has more than 500 Access applications.
+
+#### Recognizing Void's Applications
+
+Void adds no tags. Its application names follow this pattern:
+
+```text
+void-<installation>-<code>-<random>-project-zero-trust     shared project application
+void-<installation>-<code>-<random>-public-<project-id>    public exception
+void-<installation>-<code>-<random>-protected-<project-id> custom domain application
+void-<installation>-<code>-<random>-platform-health        health check exception
+```
+
+- `<installation>` is the start of your installation ID, which begins with your installation name.
+- `<code>` is 16 characters. It is the same for every application of one installation.
+- `<random>` is 32 random characters.
+- `<project-id>` is the project ID, such as `proj_abc123def456`. The project slug is not part of the name.
+
+To see the exact names Void recorded, run `void platform zero-trust status` for the shared application and the health check exception, and `void platform zero-trust project-status <project-id>` for a project's applications. There, the public exception is listed as `bypass application name` and the custom domain application as `protected application name`.
+
+### Editing Applications in the Dashboard
+
+Do not edit, rename, or delete Void's applications in the Cloudflare dashboard. Change the identity providers and policies with `void platform zero-trust configure` instead. See [Enable Zero Trust](#enable-zero-trust).
+
+You can still edit the rules inside a selected reusable policy. Void's applications use your policies as they are. Void checks them again during `void platform zero-trust configure` and `void platform zero-trust reconcile`, which stop with an error, and during `status --check`, which reports `present: false`. A policy fails this check when it now allows Everyone or any service token, or uses a Bypass or Service Auth decision.
+
+#### What Happens If You Do
+
+Void writes an application when it updates it: during platform `configure` or `reconcile`, during a project's `protect`, `public`, or `reconcile`, when a custom domain is added to or removed from that project, and while it retries a project that is not settled. Scheduled maintenance does not look for dashboard changes on settled projects. Until one of these runs, your change stays in effect.
+
+| Change in the dashboard                                | Effect                                                                                                                                                                                                | Repair                                              |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| Edit hostnames, policies, providers, or session length | Your change stays until the next update, which puts Void's settings back.                                                                                                                             | Run the reconcile command for that application      |
+| Delete the shared project application                  | Protected projects answer 403 on `<slug>.<your domain>` and `workers.dev` URLs. Their custom domains and public projects keep working.                                                                | `void platform zero-trust reconcile`                |
+| Delete a public exception                              | Visitors of that public project are asked to sign in, because the shared application now covers it.                                                                                                   | `void project zero-trust reconcile` in that project |
+| Delete a custom domain application                     | That protected project answers 403 on its custom domains.                                                                                                                                             | `void project zero-trust reconcile` in that project |
+| Delete the health check exception                      | Platform health checks fail with a redirect to sign-in, so the admin dashboard shows `dispatch` as unhealthy and `void platform upgrade` and `repair` stop at their health check.                     | `void platform zero-trust reconcile`                |
+| Rename an application                                  | Void stops updating or deleting it. Reconcile fails with `The recorded Access application no longer has its Void-owned name.` For the shared application, platform status then shows `error`.         | Rename it back to the recorded name, then reconcile |
+| Copy an application with the same name                 | Void ignores the copy while the original exists, and `disable` does not remove it. If the original is later deleted, reconcile fails with `Multiple Cloudflare Access applications are named <name>.` | Delete the copy, then reconcile                     |
+
+When Void recreates a deleted shared project application, the new application issues different Access tokens. Void then moves each protected project to it. On large installations this runs in steps, and protected projects answer 403 until Void reaches them.
+
+#### Checking for Changes
+
+```sh
+void platform zero-trust status --check
+```
+
+This compares the shared project application and the health check exception with the saved settings, and checks your selected identity providers and policies again. The output includes:
+
+```text
+checked: true
+live:
+  present: true
+  drifted: false
+```
+
+- `drifted: true` means the shared application or the health check exception no longer matches. Run `void platform zero-trust reconcile`.
+- `present: false` means Void could not read it. The application may be deleted, a selected identity provider or policy may be gone or no longer allowed, or the token may not work. Check the token and selections, then run `void platform zero-trust reconcile`.
+
+`--check` only reads. It changes nothing. It does not check public exceptions or custom domain applications. If you think one was changed, run a reconcile command.
+
+#### Repair Commands
+
+| Command                                                   | Rewrites                                                                                     | Who can run it                               |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `void platform zero-trust reconcile`                      | The shared project application, the health check exception, and every project's applications | Installation administrators                  |
+| `void platform zero-trust project-reconcile <project-id>` | One project's applications                                                                   | Installation administrators                  |
+| `void project zero-trust reconcile`                       | The linked project's applications, or pass `--project <slug>`                                | The project owner and project administrators |
+
+The two project commands work only when platform status is `ready`. While a platform change runs, or after it fails, run `void platform zero-trust reconcile` first.
+
+### What Happens During Changes
+
+Void orders every change so that a protected project never becomes public by mistake. If a step fails, the project keeps its protection, or refuses visitors with the 403 page, until the change can finish.
+
+Void's router can keep a project's previous setting for up to about a minute. During that time, some visitors may see the 403 page instead of the sign-in page.
+
+#### Protecting or Making a Project Public
+
+`void project zero-trust protect` and `void project zero-trust public` usually finish before the command returns.
+
+- **Protect.** Void covers the custom domains first, then turns on its own check, then removes the public exception. Visitors may see the 403 page for a moment before Access starts asking them to sign in.
+- **Public.** Void adds the public exception first, then turns off its own check, then removes the custom domain application. Visitors may see the 403 page for a moment before the project opens.
+
+If the command prints `Zero Trust update is still in progress`, run `void project zero-trust reconcile` to continue, or wait for the hourly maintenance. If it fails with `Cloudflare Access could not be updated. Protection remains fail closed.`, fix the cause, then run `void project zero-trust reconcile`. Until then, a project that was protected stays protected. A project you were protecting may already ask for sign-in, or answer with the 403 page, but it is never more open than before. A project you were making public may already be open on some hostnames.
+
+Run `void project zero-trust status` to follow a change. `State:` shows `reconciling` while it runs, `error` when it needs attention, and `protected` or `public` when it is done. `Last error:` explains a failure.
+
+#### Enabling and Disabling Zero Trust
+
+Large changes run in steps. Platform status shows `configuring` or `disabling`, and project owners see `Available: no`. Scheduled maintenance continues within a few minutes.
+
+When you **enable** Zero Trust:
+
+1. Void adds the public exception for each project that stays public. These projects never ask visitors to sign in.
+2. Void creates the health check exception, then the shared project application. From here, the `<slug>.<your domain>` and `workers.dev` URLs of protected projects require sign-in.
+3. Void goes through the protected projects and covers their custom domains. A project's custom domains stay open until Void reaches it.
+
+If Void cannot add a project's public exception, the project shows `error`, and its visitors are asked to sign in until the next retry succeeds. Void retries every hour, or run `void project zero-trust reconcile` once platform status is `ready`.
+
+When you **disable** Zero Trust:
+
+1. Void turns off its own check for each protected project and removes its custom domain application. Custom domains open here.
+2. Void deletes the shared project application, then the health check exception. `<slug>.<your domain>` and `workers.dev` URLs open here.
+3. Void deletes the public exceptions. Public projects stay open the whole time.
+
+#### Custom Domains
+
+A custom domain on a protected project goes live only after Void adds it to the project's custom domain application. If Access cannot be updated, the domain stays pending and is not reachable. Void tries again each time it checks the domain.
+
+When you remove a custom domain, Void removes it from the project first, then from the Access application. If the Access update fails, the project shows `reconciling` or `error` and Void retries every hour. A protected project can have up to 100 custom domains. Custom domains on public projects need no Access change.
+
+#### New Projects
+
+A new project starts protected or public based on the default for new projects. If Void cannot set up its protection, creating the project still succeeds with a warning. See [Recovery](#recovery).
+
+#### Deploys and Rollbacks
+
+Deploys and rollbacks wait while a project's protection is not settled, so a deploy cannot publish a project before its protection is in place. They are refused with `Zero Trust protection for this project is not ready`, followed by the reason:
+
+- `Project Zero Trust is still being initialized.`
+- `The project public exception is still reconciling.`
+- `Project Zero Trust is still reconciling.`
+
+If the saved platform configuration is invalid, they are refused with `The platform Zero Trust configuration is invalid.` instead. Ask a platform administrator to repair it.
+
+A project that is already protected can still deploy during a platform-wide change. While it is being made public, deploys wait until that finishes. See [Project Overrides](#project-overrides) for what to do when a deploy is refused.
+
+### Caching
+
+Responses for signed-in visitors are never shared between visitors. Void skips its shared caches for every request that carries an Access token: [ISR](/guide/edge/revalidation#cache-bypass) and the [static asset edge cache](/guide/edge/static-assets#non-hashed-assets). Each visitor gets a response made for their request.
+
+On a protected project, this means:
+
+- pages render on every request, and ISR never serves a cached page;
+- static files and hashed assets skip the edge cache;
+- the project handles more requests and may respond more slowly than a public project.
+
+Public projects keep using the shared caches as usual.
+
+## Recovery
+
+A project never becomes public by mistake while a change is in progress. See [What Happens During Changes](#what-happens-during-changes).
+
+- **Status stays `configuring` or `disabling`.** Large changes run in steps. Scheduled maintenance continues them within a few minutes, or run `void platform zero-trust reconcile`.
+- **Status shows an error.** Fix the cause shown, such as token permissions or the application limit, then run `void platform zero-trust reconcile`. Otherwise Void retries every hour.
+- **One project shows an error.** The rest of the change still finishes. Void retries the project every hour, or its owner or a project administrator can run `void project zero-trust reconcile`. Until then, a project that was already protected stays protected, and a project being newly protected is never more open than before.
+- **Adding a domain stays pending because of a project.** Void publishes the new domain only after every project is ready for it. Platform status shows an error that names the projects it could not update. Check each one with `void platform zero-trust project-status <project-id>`, fix the cause, then run `void platform zero-trust reconcile` or rerun the domain command. Void also retries every hour. Your `workers.dev` URLs keep working meanwhile.
+- **A new project could not be set up.** Creating the project still succeeds with a warning. Void retries every hour, or run `void project zero-trust reconcile`.
+- **The saved API token expired or was revoked.** Run `void platform zero-trust configure --token-stdin` with a replacement token and the same identity providers, policies, and `--protect-new-projects` choice. Omit `--existing-projects`. Void continues the unfinished change, including an unfinished disable. Finish it before changing other settings.
+- **A selected identity provider or policy was deleted.** Run `void platform zero-trust disable` to stop the unfinished setup and remove its applications. This makes projects public. Then configure Zero Trust again with the new selections.

package/skills/void/docs/guide/platform/development/local.md

@@ -51,7 +51,7 @@ The command disables the optional build containers, so basic API and admin work
 does not require Docker. To develop managed builds, install Docker and run the
 API with containers enabled.
 
-Open `http://localhost:8787/admin/`. Setup writes local development values to the API and dashboard `.dev.vars` files, including the development authentication bypass and local database connection. Those files are ignored by Git. Production installations get separate credentials through the installer.
+Open `http://localhost:8787/admin/`. Setup writes the API's local database connection and development authentication bypass to `platform/packages/api/.dev.vars`. It configures `platform/packages/dashboard/.env` for the separate dashboard. Both files are ignored by Git. Production installations get separate credentials through the installer.
 
 The API's development bypass lets you work on the browser admin UI without setting up OAuth. Operator CLI sessions still require administrator authentication; they do not use the browser bypass.
 
@@ -63,7 +63,7 @@ The dashboard is a separate source app. After API setup, start it in another ter
 vp run --filter @voidcloud/dashboard dev
 ```
 
-Its local `.dev.vars` should point to the API you started:
+Setup points the dashboard's local `.env` at the API you started:
 
 ```dotenv
 API_URL=http://localhost:8787

package/skills/void/docs/guide/platform/installation/domains.md

@@ -15,7 +15,7 @@ void platform domain set example.app
 
 The command selects your installed platform (or offers a picker), finds or creates its zone, sets up DNS and routing, and verifies HTTPS before publishing the new application URLs. Set the management token as described in [installation setup](/guide/platform/installation/setup) when creating DNS or a zone. Grant the existing runtime token **Cache Purge: Purge** on the new zone; Void checks that permission through the running platform without asking you to paste its token again.
 
-If nameservers or certificates are pending, follow the printed guidance and rerun the same command. Your workers.dev app URLs continue working during and after setup. Projects, deployments, secrets, and the platform API URL stay the same, so developers do not reconnect and configured login callbacks do not change. DNS and configuration changes may take time to propagate.
+If nameservers, certificates, or project Zero Trust protection are pending, follow the printed guidance and rerun the same command. Void preserves each project's public or protected setting before making the new URLs available. Your workers.dev app URLs continue working during and after setup. Projects, deployments, secrets, and the platform API URL stay the same, so developers do not reconnect and configured login callbacks do not change. DNS and configuration changes may take time to propagate.
 
 Use `--installation <id>` to select an installation explicitly, `--zone example.com` for an app domain such as `apps.example.com`, or `--dedicated-zone` for catch-all routing on a dedicated zone. Nested domains still need the wildcard certificate described below. This command adds the first domain; replacing an existing application domain is not currently supported. It uses the installed runtime and does not require `--runtime` or an app redeploy.
 

package/skills/void/docs/guide/platform/installation/first-deployment.md

@@ -80,3 +80,7 @@ Void shows the proposed access change and asks you to confirm it. Once approved,
 To see who can join, run `void platform signup show`. You can also allow an email address or a domain such as `*@example.com`. For an OIDC user without verified email, use `void platform signup allow identity <connection-id> <subject>`; the subject match is exact and the provider's domain or group restrictions still apply. Remove that grant with `void platform signup disallow identity <connection-id> <subject>`. `void platform signup open` permits public signup; `void platform signup restrict` requires an allowlist match again.
 
 Your administrator session lasts for one hour. Use it to inspect users, projects, logs, and platform health. The [Platform Administration guide](/guide/platform-administration) walks through those workflows, previews, and automation. You can also open `<API origin>/admin/login` to use the browser admin UI.
+
+### Protect Project Hostnames with Zero Trust
+
+After installation, an administrator can require Cloudflare Access on new project hostnames while allowing each project owner or project administrator to opt out. This is independent of Access login and protection for the platform API itself, and it needs its own Cloudflare API token. See [Project Zero Trust](/guide/platform/administration/zero-trust) for the requirements, setup command, and recovery.

package/skills/void/docs/guide/platform/installation/prerequisites.md

@@ -73,7 +73,7 @@ Void does not require a particular database provider. Use an existing PostgreSQL
 
 1. Create a fresh database or project dedicated to the platform, with no existing application tables. Use a database role that can create and manage its tables and schemas.
 2. Open the provider's connection details and select the primary database. Use a direct connection or a session-mode pooler, not transaction pooling. The connection must work from both your computer and Cloudflare.
-3. Copy the PostgreSQL connection URL, including the password and SSL settings, into your password manager. Paste only the URL—not a surrounding `psql` command—into Void's `PostgreSQL DATABASE_URL` prompt.
+3. Copy the PostgreSQL connection URL, including the password and SSL settings, into your password manager. Paste only the URL—not a surrounding `psql` command—into Void's `PostgreSQL DATABASE_URL` prompt, as the provider gives it, including SSL settings such as `sslmode=verify-full`. A Hyperdrive that Void creates trusts only public certificate authorities, so if your database uses a private certificate authority, use a separately managed Hyperdrive, as described below.
 
 | Provider                                                                     | Connection setup                                                                                                                                                                                                                                      |
 | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/skills/void/docs/guide/platform/installation/uninstall.md

@@ -31,7 +31,7 @@ void platform uninstall [id] --plan
 void platform uninstall [id]
 ```
 
-Uninstall blocks platform traffic, removes transient Queues, and records the resources left for you to review. By default, Workers, KV, R2, Hyperdrive, the dispatch namespace, and AI Gateway remain in your account. Adopted resources, external PostgreSQL, zones, DNS records, routes, custom domains, and Cloudflare Access resources are always retained.
+Uninstall blocks platform traffic, removes Queues that no remaining platform Worker uses, and records the resources left for you to review. By default, Workers, the Queues they use, KV, R2, Hyperdrive, the dispatch namespace, and AI Gateway remain in your account. Adopted resources, external PostgreSQL, zones, DNS records, routes, custom domains, and Cloudflare Access resources are always retained.
 
 To also remove eligible data resources owned by the installer:
 
@@ -39,10 +39,25 @@ To also remove eligible data resources owned by the installer:
 void platform uninstall [id] --purge-data
 ```
 
-Even with `--purge-data`, Void retains Workers, R2, AI Gateway, DNS records, routes, custom domains, Access resources, adopted resources, external PostgreSQL, and zones. Review those in the Cloudflare dashboard if you want to remove them.
+Even with `--purge-data`, Void retains Workers, the Queues they use, R2, AI Gateway, DNS records, routes, custom domains, Access resources, adopted resources, external PostgreSQL, and zones. Review those in the Cloudflare dashboard if you want to remove them.
+
+### Remove retained resources
+
+Cloudflare refuses to delete a resource while a platform Worker still uses it. In the Cloudflare dashboard, remove what is left in this order, skipping anything already gone:
+
+1. Delete the platform DNS record, Worker routes, and custom domains.
+2. Open each platform Queue and remove the platform API Worker from its consumers.
+3. Delete the platform Workers.
+4. Delete the platform Queues.
+5. Delete the application Workers in the dispatch namespace, then delete the namespace.
+6. Delete the platform KV namespaces and Hyperdrive configuration.
+7. Empty the R2 bucket, then delete it.
+8. Delete the AI Gateway.
 
 If installation configured Cloudflare Access, the uninstall plan lists its recorded applications and service tokens with their ownership and IDs. Review them in Zero Trust after uninstall. Remove installer-created resources only when nothing else uses them; resources connected from an existing company setup remain under their owner's control.
 
+Uninstall does not remove the applications created for [project Zero Trust](/guide/platform/administration/zero-trust). While Zero Trust is enabled or still has Access applications, uninstall and `--plan` stop before any change and list those applications. Run `void platform zero-trust disable` first. Uninstall reads this from the installation database, so it also stops when the database cannot be reached.
+
 ::: details Why some resources require manual cleanup
 
 Resources that may have been shared or repurposed require manual review before deletion. Void verifies ownership, keeps those resources in place, and blocks platform traffic.

package/skills/void/docs/guide/platform-administration.md

@@ -12,5 +12,6 @@ The operator commands for users, projects, deployments, and system status requir
 
 - [Sign-in and Access](/guide/platform/administration/access)
 - [Users and Projects](/guide/platform/administration/projects)
+- [Project Zero Trust](/guide/platform/administration/zero-trust)
 - [Email](/guide/platform/administration/email)
 - [Operations](/guide/platform/administration/operations)

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

@@ -4,82 +4,111 @@ outline: deep
 
 # Sandboxes
 
-Use a Cloudflare Sandbox to run commands, work with files, and expose ports from server code. Each session gets an isolated container.
+Use a Cloudflare Sandbox to run commands, work with files, and connect to servers from server code. Each Sandbox ID selects an isolated container.
 
 ```ts
 import { defineHandler } from 'void';
 import { getSandbox } from 'void/sandbox';
 
 export const POST = defineHandler(async (c) => {
-  const { command } = await c.req.json<{ command: string }>();
   const sandbox = await getSandbox('default');
-  const result = await sandbox.exec(command);
-
-  return c.json(result);
+  const process = await sandbox.exec(['node', '--version']);
+  const result = await process.output();
+
+  return c.json({
+    exitCode: result.exitCode,
+    stdout: new TextDecoder().decode(result.stdout),
+    stderr: new TextDecoder().decode(result.stderr),
+  });
 });
 ```
 
-Importing from `void/sandbox` enables the required Sandbox resources. Native Cloudflare deployments add the `SANDBOX` Durable Object and Container metadata to the Worker. Void Platform deployments provide the same runtime API through a managed Sandbox controller.
+Importing from `void/sandbox` enables the required resources. Local development, native Cloudflare deployments, and Void Platform share the same runtime API.
 
 ## Configuration
 
-Most apps do not need config. The default binding is `SANDBOX`, the Durable Object class is `Sandbox`, and local development, native Cloudflare deploys, and Void Platform all use the published image matching the installed `@cloudflare/sandbox` version.
+Most apps do not need config. The default binding is `SANDBOX`, the Durable Object class is `SandboxV1`, and the default environment provides Node.js 24 on Debian Trixie. Local development and native deploys build Void's packaged Dockerfile, so Docker must be running. Managed platform deploys use Cloudflare's managed Node.js image.
 
 Use `void.config.ts` when you need a custom image or container size:
 
-```json
-{
-  "sandbox": {
-    "image": "./Dockerfile.sandbox",
-    "platformImage": "registry.example.com/acme/sandbox:latest",
-    "instanceType": "lite",
-    "maxInstances": 2
-  }
-}
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  sandbox: {
+    image: './Dockerfile.sandbox',
+    platformImage: 'registry.cloudflare.com/<account-id>/sandbox@sha256:<digest>',
+    instanceType: 'standard-1',
+  },
+});
 ```
 
-Available fields:
+| Field               | Default                     | Description                                                          |
+| ------------------- | --------------------------- | -------------------------------------------------------------------- |
+| `binding`           | `SANDBOX`                   | Binding name for local and native Cloudflare use                     |
+| `className`         | `SandboxV1`                 | Durable Object class for local and native Cloudflare use             |
+| `containerName`     | `void-sandbox-v1`           | Cloudflare container application name                                |
+| `image`             | Packaged Node.js Dockerfile | Dockerfile or digest-pinned Cloudflare registry image for native use |
+| `imageBuildContext` | Directory of `image`        | Docker build context                                                 |
+| `platformImage`     | `cloudflare/debian-trixie`  | Image used by managed platform deploys                               |
+| `instanceType`      | `lite`                      | `lite`, `standard-1`, `standard-2`, `standard-3`, or `standard-4`    |
+
+Custom images must include the helper matching Void's installed Sandbox SDK version. The SDK image supplies this binary, but is not a runnable environment itself:
+
+```dockerfile
+FROM node:24.21.0-trixie-slim
+COPY --from=docker.io/cloudflare/sandbox:1.0.0 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
+WORKDIR /workspace
+CMD ["sleep", "infinity"]
+```
 
-| Field               | Default                    | Description                                                           |
-| ------------------- | -------------------------- | --------------------------------------------------------------------- |
-| `binding`           | `SANDBOX`                  | Binding name for local and native Cloudflare use                      |
-| `className`         | `Sandbox`                  | Durable Object class for local and native Cloudflare use              |
-| `containerName`     | `void-sandbox`             | Cloudflare container app name                                         |
-| `image`             | Matching sandbox SDK image | Dockerfile path or registry image for local and native Cloudflare use |
-| `imageBuildContext` | Directory of `image`       | Docker build context for local and native Cloudflare use              |
-| `platformImage`     | Matching sandbox SDK image | Registry image used by `void deploy`                                  |
-| `instanceType`      | `lite` on Void deploy      | Container size, such as `lite`, `basic`, `standard-1`                 |
-| `maxInstances`      | `20` on Void deploy        | Maximum number of container instances                                 |
+For a managed platform, push your custom image to that platform account's Cloudflare registry and set `platformImage` to its digest-pinned reference. If `image` is already a Cloudflare registry reference, it also becomes the default `platformImage`. External registry references and mutable tags are not supported by the new scheduling policy. See [Cloudflare's image management guide](https://developers.cloudflare.com/containers/guides/image-management/#push-images-to-the-cloudflare-registry).
 
 ## Runtime API
 
-`getSandbox(id, options)` returns the SDK sandbox stub for a session id. IDs are normalized by default so user-provided session ids can safely map to Durable Object names.
+`getSandbox(id, options)` resolves a Sandbox without starting it. The first command, file operation, or port request starts the container. IDs contain 1–63 characters and are lowercased by default; pass `normalizeId: false` to preserve case.
 
 ```ts
 import { getSandbox } from 'void/sandbox';
 
-// inside an async handler
-const sandbox = await getSandbox(`user-${user.id}`);
-await sandbox.writeFile('/tmp/input.txt', 'hello');
-const result = await sandbox.exec('cat /tmp/input.txt');
+const sandbox = await getSandbox(`user-${user.id}`, {
+  inactivityTimeoutMs: 10 * 60 * 1000,
+  enableInternet: false,
+});
+await sandbox.files.writeFile('/workspace/input.txt', 'hello');
+const process = await sandbox.exec(['cat', '/workspace/input.txt'], {
+  signal: AbortSignal.timeout(5_000),
+});
+const { stdout, exitCode } = await process.output();
+const text = new TextDecoder().decode(stdout);
 ```
 
-For code that must run on both deployment targets, use `getSandbox()`. Direct access through `c.env.SANDBOX` is available only on local and native Cloudflare deployments; managed platforms intentionally expose the application Sandbox API without the underlying lifecycle namespace.
+Commands take an executable and arguments as an array. For shell syntax, explicitly run `['sh', '-c', command]`. Execution options include `cwd` (default `/workspace`), `env`, `user`, `signal`, `pty`, `stdin`, `stdout`, and `stderr`.
 
-## State persistence
+`exec()` returns a process immediately after it starts. Read its `stdout` and `stderr` streams, or call `output()` to collect both as `ArrayBuffer`s together with the exit code. `exitCode` is a promise; `kill(signal?)` and `resize(cols, rows)` are asynchronous. Use `stdin: 'pipe'` to receive a writable `stdin` stream. A process can continue running after a request returns, until it exits or its container stops. When streaming output from a long command, await `process.exitCode` alongside consuming its streams. This keeps an explicit command wait active even while the command produces no output; unattended background commands can stop when the Sandbox becomes idle.
 
-A sandbox has a Durable Object identity and a container that can restart:
+File operations live under `sandbox.files`: `readFile`, `writeFile`, `stat`, `lstat`, `readDirectory`, `mkdir`, `rename`, and `remove`. `readFile()` returns a streaming `Response`; use `.text()`, `.arrayBuffer()`, or `.body`. `writeFile()` accepts text, binary data, or a byte stream. Relative file paths require an explicit `cwd` option.
 
-`getSandbox(id)` selects the same Durable Object for that ID within a deployment. Native Cloudflare deployments preserve that namespace across Worker versions. Each managed platform deployment has its own namespace; rolling back to a retained deployment reconnects to that deployment's namespace.
+To reach a server inside the container, call `sandbox.fetch(port, new Request(url))`. `sandbox.running()` checks whether the container is running; `sandbox.destroy()` stops it.
 
-Files, running processes, exposed ports, and in-memory shell sessions last only as long as the container. It can stop after inactivity (the SDK defaults to `sleepAfter: "10m"`), crash, or restart during platform scheduling. `keepAlive: true` disables the idle timer but doesn't prevent other restarts.
+`getSandbox()` options include `inactivityTimeoutMs` (default ten minutes, maximum six hours), `enableInternet` (default `false`), and string `labels`. Internet access and labels take effect on the next container start. `binding` selects a custom native binding; managed platforms use the configured binding.
 
-Save anything you need to keep in Durable Object storage, your database, KV, or R2. The SDK also provides helpers to back up and restore directories through R2. Deleting the project on a Void platform removes both layers; routine container restarts only lose container state.
+For code that runs on both deployment targets, use `getSandbox()`. Direct access through `c.env.SANDBOX` is available only on local and native Cloudflare deployments.
+
+## State persistence
+
+`getSandbox(id)` selects the same Durable Object for that ID within a deployment. Native Cloudflare deployments preserve that namespace across Worker versions. Each managed platform deployment has its own namespace; rolling back to a retained deployment reconnects to that deployment's namespace.
+
+Files, running processes, and listening servers last only as long as the container. It can stop after inactivity, crash, or restart. Save anything you need to keep in your database, KV, or R2. For custom Durable Object implementations, `void/sandbox` also exports the SDK's `Files`, `DirectoryBackup`, `DirectoryBackupGateway`, `S3Mount`, and `S3Gateway` helpers. Deleting a project on a Void platform removes both its Durable Objects and containers.
 
 ## Deployment
 
-`void deploy` creates a deployment-scoped Sandbox controller and container application in the Void platform account. The controller owns container lifetime, concurrency admission, and runtime accounting; the application receives only the Sandbox operations exposed by `getSandbox()`.
+Sandboxes require [Workers Paid](https://dash.cloudflare.com/?to=/:account/workers/plans) and Containers access. Void checks this before provisioning or building. A managed platform's runtime token needs Account / Containers: Edit and Account / Cloudchamber: Edit. Applications without Sandbox do not require Containers or perform this entitlement check.
+
+`void deploy --platform cloudflare` builds native images and deploys the Sandbox alongside the application. `void deploy` on a connected Void Platform creates a deployment-scoped Sandbox controller, which enforces concurrency and runtime limits. Upgrade the platform before deploying an application built with this Sandbox API.
+
+## Moving from Sandbox SDK 0.x
 
-Platform deploys require a registry image reference. The default sandbox works without extra config. If `sandbox.image` points at a custom local Dockerfile, also set `sandbox.platformImage` to an image you have already pushed to a registry.
+Update string commands to argument arrays, move file calls under `.files`, and consume process output and file responses as shown above. Replace `sleepAfter` and `keepAlive` with `inactivityTimeoutMs`; remove `maxInstances` from configuration. The old `Sandbox` export, sessions, code interpreter, process-list helpers, and preview-URL helpers are no longer part of this API.
 
-Managed Sandboxes require Workers Paid on the platform's Cloudflare account. The platform runtime token needs Account / Containers: Edit and Account / Cloudchamber: Edit. These are checked only when an application that uses Sandbox is deployed; installing or upgrading a platform and deploying other applications does not probe Containers access.
+Existing native 0.x Sandboxes need a new Worker configuration and namespace. Back up container files and any Durable Object data, choose a fresh `worker.name`, and remove the old Sandbox bindings, containers, and migrations from that new configuration before deploying. The new default class is `SandboxV1`; existing state does not transfer automatically. Retain the old Worker until you have validated the replacement and restored your data, then clean up its resources. See [Cloudflare's scheduling-policy migration guide](https://developers.cloudflare.com/containers/guides/migrate-to-durable-object-scheduling-policy/).

package/skills/void/docs/integrations/cloudflare.md

@@ -360,7 +360,7 @@ ISR uses the shared cache protocol. Entries are scoped to a deployment and hostn
 
 With Cloudflare selected, `void secret`, `void domain`, `void project status|list|logs|rollback`, and remote `void db` commands use the saved Worker and account. Database commands operate on the selected D1 database. Logs are a live tail; Void doesn't provide hosted log history for direct deploys.
 
-Custom domain changes update routes immediately without rewriting schedules, queues, or workflows. Removing the final custom domain requires `CLOUDFLARE_API_TOKEN` with Workers Scripts: Edit because that operation uses Cloudflare's domain-record API.
+Custom domain changes update routes immediately without rewriting schedules, queues, or workflows. Removing the final custom domain uses your browser session from `void cloudflare login` or an API token with Workers Scripts: Edit permission.
 
 `void project delete` doesn't remove direct Cloudflare resources, which may be shared. Review their use and remove them explicitly in Cloudflare.