Updating

New versions ship from the project repository. Pull them with Git on a shell-capable host, or apply a release archive on shared hosting. Both preserve everything you've created.

Checking your current version

Your current version is shown at the bottom-right of the Studio screen in the status bar. You can also find it in the VERSION file in your installation root.

Git Update (preferred for SSH-capable installs)

If your installation is a Git checkout (typical on a VPS, Forge, RunCloud, or any host with SSH), VoxelSite can update itself by pulling from the repository. Nothing to download, and vendor/ updates with it.

The Git Updates card appears in Settings only when all three of these are true: the install is a git clone (there's a .git/ directory in the root), the git command is available, and PHP allows proc_open. On shared hosting without these, use the archive methods below; the card won't appear.

1. Log in to VoxelSite Studio at yourdomain.com/_studio/
2. Go to Settings and find the Git Updates card
3. It shows your branch and whether updates are available (e.g. "3 updates available")
4. Click Update now, then Reload Studio when it finishes

VoxelSite fetches the latest commit, resets the application to match it (system files only), and runs any pending database migrations. Your pages, settings, database, and uploaded files are never touched. They live outside version control.

Safety. The updater refuses to run if it detects local edits to tracked files ("Local code changes detected") rather than discarding your work, and it never runs git clean, so untracked content stays in place. A web request can't hang on a credential prompt; Git runs non-interactively with a hard timeout.

Setting up Git updates

To put an install on the Git path, deploy it as a clone instead of unzipping (see Installation → Install via Git). The Studio button then pulls from the clone's existing remote.

Versions, tags, and release notes

Each release is a Git tag (for example v1.2.0), and the matching GitHub release holds the notes for what changed. The Git Updates card in Settings always moves you to the latest commit on your branch, which is the easy path for most installs.

To pin a specific version from a shell, fetch the tags and check one out:

cd /path/to/your/webroot
git fetch --tags
git checkout v1.2.0

Open the Studio afterwards so VoxelSite applies any pending migrations, the same as after an in-app update. Run git checkout main to return to tracking the latest.

In-App Update (recommended for shared hosting)

1. Download the latest .zip release
2. Log in to VoxelSite Studio at yourdomain.com/_studio/
3. Go to Settings
4. Scroll to the Update section
5. Click Choose File and select the .zip you downloaded
6. Click Upload & Update
7. Wait for the confirmation message - it will show how many files were updated
8. Click Reload Studio to load the new version

That's it. VoxelSite overwrites its own system files while preserving everything you've created.

Upload too large? If your hosting limits the upload size and the zip is rejected, use the FTP Upload method below instead.

FTP Upload + In-App Apply

If your hosting's PHP upload limit is too low for the zip file, you can upload it via FTP and apply it from the Studio:

1. Download the latest .zip release
2. Connect to your server via FTP/SFTP
3. Upload the .zip file (don't extract it) to the /dist/ folder in your VoxelSite installation root. Create the folder if it doesn't exist.
4. Log in to VoxelSite Studio at yourdomain.com/_studio/
5. Go to Settings and scroll to the Update section
6. The uploaded zip will appear automatically with its version number and an Apply Update button
7. Click Apply Update and confirm
8. Wait for the confirmation message, then click Reload Studio

This method bypasses the PHP upload limit entirely since the file is already on the server. After the update completes, you can delete the .zip from /dist/ to save disk space.

What is preserved

All update methods preserve your content and data:

Manual Update (FTP)

Use this method as a last resort - for example, if neither of the methods above work for your hosting setup.

1. Download the latest .zip release
2. Extract it on your computer
3. Upload the following directories to your server via FTP/SFTP, overwriting the existing ones:
   • _studio/engine/
   • _studio/ui/
   • _studio/api/
   • _studio/static/
   • _studio/prompts/
   • _studio/templates/
   • vendor/
4. Upload the following root files, overwriting the existing ones:
   • _studio/index.php
   • _studio/install.php
   • _studio/.htaccess
   • submit.php
   • mcp.php
   • VERSION
5. Do NOT overwrite these directories:
   • _studio/data/ - your database and settings
   • _studio/preview/ - your website pages
   • _studio/revisions/ - your undo history
   • _studio/snapshots/ - your snapshots
   • assets/ (except assets/icons/) - your uploaded content
   • _data/ - your form submissions
6. Visit yourdomain.com/_studio/ to verify

Backup first

While the updater is designed to be safe, it's good practice to back up before major updates:

• _studio/data/ - database and configuration
• _studio/preview/ - your website pages
• assets/ - uploaded images, files, and fonts
• _data/ - form submissions

Most hosting control panels have a one-click backup option, or you can download these directories via FTP.

Troubleshooting

Upload fails or times out - Your hosting may limit upload size or execution time. Try the FTP Upload + In-App Apply method above - upload the zip to /dist/ via FTP and apply it from the Studio. Alternatively, ask your hosting provider to increase upload_max_filesize and max_execution_time in PHP settings.

"This doesn't look like a VoxelSite update package" - Make sure you're uploading the original .zip release, not a file you re-zipped yourself. The updater looks for a VERSION file inside the zip to verify it's genuine.

ZipArchive error - The ZipArchive PHP extension is required and checked during installation. If you see this error after a server migration or PHP upgrade, ask your hosting provider to re-enable it.

White screen after update - Clear your browser cache (Ctrl+Shift+R or Cmd+Shift+R) and reload. If the issue persists, check your hosting error log for PHP errors.