PR Preview VPS

A Preview VPS runs one pull request's Matrix OS host bundle on a disposable computer. Use it to validate shell, gateway, Chat, dictation, onboarding, and host-service changes without updating a customer computer.

Create a Preview

Add the preview-vps label to a same-repository pull request. The protected workflow builds the exact PR commit, publishes an immutable bundle without promoting a release channel, provisions or resumes pr-<number>, deploys that exact bundle, and comments the URL on the pull request.

Fork PRs and unapproved workflow code do not receive Preview infrastructure, deployment credentials, or funded capabilities.

The Preview is deleted when the pull request closes. A daily reaper also removes stale Preview computers.

Funded Chat and dictation

A newly deployed Preview can receive a short-lived Preview-only allowance for:

• Matrix-funded Chat, with both a request limit and a maximum AI-spend limit.
• Dictation, with a separate request limit.
• One active funded operation at a time.

Matrix AI Settings shows separate Preview Chat requests and Preview dictation requests with the local expiry date, time, and time zone. Chat credit is dollar-denominated and remains separate: it is not the Preview request counter and does not change from 25 to 24 after a Preview request. Chat also shows the remaining Preview dictation requests beside the microphone, keeps the exhausted state visible, and refreshes the count after a transcription attempt in Web Desktop, Web Canvas, and Electron Desktop.

The allowance does not use or change the owner's primary computer balance. Preview dictation never falls back to the owner's paid credit, and Preview Chat cannot be topped up. Shared Preview users receive the bounded machine capability only; they do not gain access to the owner's personal integrations, connected accounts, billing state, or production credits.

Security boundary

Preview trust comes from the server's machine record, not from a pr-* name. Access is bound to the exact owner, machine ID, runtime slot, and token generation. A credential copied from the Preview cannot be reused by another owner, machine, slot, or replacement Preview.

Deleting the computer, rotating its token generation, or reaching the allowance expiry invalidates the old access. Re-running the deployment does not refill or extend an existing allowance.

Provider keys stay on Matrix's control plane. The Preview receives only a short-lived credential for its exact bounded capability, which limits the impact even though a Preview Terminal user can inspect the host.

Verify a change

Before treating a Preview as review-ready:

1. Confirm the Preview reports the exact PR commit and bundle version.
2. Complete one real funded Chat turn and confirm the Preview request count decreases.
3. Dictate one real audio sample and confirm the editable transcript and remaining dictation count.
4. Confirm the owner's primary funded-AI balance is unchanged.
5. Capture each affected running surface, including Web Desktop, Web Canvas, and Electron Desktop when changed.

Attach the exact-build evidence to the pull request. Automated tests and mockups are useful, but they do not replace evidence from the affected running Preview.

Troubleshooting

If funded Chat or dictation is unavailable, check the protected workflow's activation result and the Preview's remaining allowance. A Preview that is unhealthy, expired, deleted, replaced, or not server-classified as a Preview must fail closed.

Do not edit host environment files, add provider credentials, recreate a customer primary, or infer eligibility from the handle. Fix the workflow or control-plane condition and redeploy the same exact PR build.

Related

• Dev VPS
• Testing
• Review pipeline
• Releases