Honest answers about how GWS Backup works.
Yes, for up to 10 client workspaces. GWS Backup is free under the GWS Backup Free Licence, for personal and commercial use alike — including MSPs serving paying clients. No trial clocks, and no feature withheld: the free licence is the complete application, not a cut-down edition of it. Above 10 workspaces is by enquiry — there is no price list, and asking costs nothing.
Development is funded entirely by voluntary donations. If the software earns its keep, a donation of any size keeps it alive. It unlocks nothing and raises no limits — there is nothing held back to sell you.
No — and that is deliberate. There is no separate donor edition: same software, same features, and the same ten-workspace limit. Donating raises no limit and unlocks nothing, because nothing is held back to sell you.
What it does buy is the time to keep building this. We’ll be in touch to say thank you personally, and when we’re able to we will recognise supporters in other ways — watch this space. If you need more than ten workspaces, that is a separate conversation rather than a donation.
No. GWS Backup is free to use, but not open source. Years of evenings and weekends live in this codebase, and keeping the source closed stops others repackaging that work and re-marketing it as their own. You may not rebrand, resell or redistribute the software.
If you'd like it under your own brand legitimately, that's what our white-label programme is for.
Yes — commercially. You can purchase GWS Backup as a white-label product sold under your own identity, or for a one-off fee we'll fit your logo, colours and report templates into the app for you.
Use the contact form with details of your business and we'll come back with a straightforward quote.
The next release — our latest beta — is due on 2 September 2026. If you register now, your licence key carries straight over: updates never touch your licence or settings.
Releases are announced on the development roadmap.
For the free edition, please allow 1–2 days for a response. For white-label and custom-branded packages, enquiries are usually answered the same day (UK time).
Download the release files, create a Node.js application in cPanel — Setup Node.js App or Application Manager, whichever your host provides (Node 22.5 or newer), upload and extract the files into the application root, and activate your free licence key on first run.
The full step-by-step walkthrough lives on our Install Guide, and a README with the same instructions is included inside the download.
Never inside public_html. The application folder contains your encrypted credentials database and encryption keys — those files must not be web-accessible. Install into a folder in your home directory instead (e.g. ~/gwsbackup).
We also strongly recommend serving it on a subdomain with a random, unguessable name — something like vault-k7x93q.yourdomain.com rather than backup.yourdomain.com. Bots scan predictable subdomain names for login panels around the clock; a random name keeps your installation invisible to them.
Yes. GWS Backup will not run without a licence key — on first run the app asks for your key and stays locked until a valid one is activated. Keys are free — for now they're issued personally, so request yours via the contact form (usually answered within 1–2 days). Automatic key delivery by email is planned for the near future.
Validation requires the server to have outbound internet access, and each key permits one running installation at a time.
A cPanel account that can run a Node.js application — either Setup Node.js App (CloudLinux Node.js Selector) or Application Manager (cPanel’s own); which one you get is decided by your host. Then Node.js 22.5 or newer (required for the built-in SQLite engine), PHP with ZipArchive for the update script, and outbound HTTPS access.
The app needs about 100 MB of disk plus roughly 50 MB of RAM per client workspace. Your backup data itself is stored in your destination — Google Drive, S3, Azure or local disk — not on the web server.
Upload the new release zip and its matching installer into your application folder, then run the installer — for example php gwsbackup-cpanel-0.96-installer.php. It backs up your databases first, including every per-client index, then extracts the new build and leaves your database, licence and settings untouched. It also refuses to run if the payload’s version does not match its own, and clears out installers from earlier releases. Restart the app in cPanel afterwards.
New releases are announced on the blog, and the feature list always reflects the current version.
In this order. Each step depends on the one before it.
After that the app runs itself. The things worth checking occasionally are the dashboard for parked or failed runs, and the Activity Log for anything you did not expect.
The first run for a client indexes every email, file and calendar event from the beginning of time and downloads all of it. For a mailbox with years of history that is genuinely hours of work, and it is bounded by how fast Google will hand the data over, not by your server.
Every run after it is incremental: the app checks what has changed since last time and only downloads that. A typical daily run finishes in minutes, even for a client whose first run took most of a day.
If a first run is interrupted — a restart, a crash, a quota stop — nothing is lost. The next run continues from where it left off rather than starting again.
Three things, all on the client's side:
The connection wizard walks through each step and shows the exact scope string to paste. If delegation is missing or incomplete you will see unauthorized_client — see the troubleshooting section.
Backup is read-only: enough to list and download mail, Drive files, calendars and contacts. It is the least access that still lets the product do its job, and it is what most clients should grant.
Admin adds the administrative scopes — user directory, suspensions, spam management, security reports. It powers the Workspace Admin screens and the security figures in reports. A client on the Backup tier simply gets "not measured" for those, rather than an error.
The tier is per client and can be changed later, but the client's delegation grant has to be updated to match — Google's delegation is all-or-nothing per request, so a scope you ask for that has not been granted fails the whole token exchange rather than just that one feature.
The licence is free and does not expire. What it limits is not features but use: one running installation per key, no reselling or redistributing the software, and no rebranding it as your own product.
You may use it commercially — including running backups for your own paying clients as a managed service. That is explicitly allowed.
The number of workspaces you can protect comes from your key. If you hit the limit, adding a client is refused with a message naming the cap.
For every item it compares what Google reports against what is already in the backup index. Unchanged items are skipped without downloading anything — that is why a run can check 150,000 items in twenty minutes and transfer almost nothing.
A run starts fresh rather than incremental in only a few cases: the client has never been backed up, the backup destination was changed, or the run folder at the destination was deleted. A fresh run re-seeds everything and then continues incrementally.
Moving a file in Drive does not change its modified time, so a relocated file would normally be skipped and its recorded path go stale. The app resolves the current path from data it already has during the skip check and quietly corrects the index.
Parked means paused on a Google limit, not failed. Nothing has been lost and nothing needs redoing — the run stops cleanly, records exactly what it had finished, and picks up from there.
The usual cause is Google's per-user transfer cap: 750 GB of upload per account per 24 hours, counted across My Drive and all shared drives, and it includes copies. Unlike the API quota, Google states this cap cannot be increased and cannot be requested — waiting is the only option. A parked restore resumes automatically once the window passes (up to five unattended resumes per run), and you can always resume it by hand from the restore screen.
If you need it finished sooner, the cap is per user, so splitting the work across several target accounts multiplies your real throughput — three targets means three separate 750 GB allowances. The restore wizard estimates this before you start.
What will not help: routing the transfer through another machine or rotating service accounts and projects. The cap is enforced against the target account whatever the traffic's origin, and rotating credentials to dodge it puts the customer's Workspace at risk.
No. Google limits how fast anyone can pull data out. When the app hits that, it pauses, waits a calculated cooldown (exponential backoff) and resumes exactly where it stopped. No data is lost and no run needs restarting. Seeing these in a log is normal for a large backup.
You can raise this one yourself. The per-minute limit is a quota on your Google Cloud project — 1,000,000 quota units per minute per project and 325,000 per user by default — and it is adjustable, free, from the Cloud console under IAM & Admin → Quotas & System Limits (search for the Drive API). Approval is not guaranteed, but for a busy console it is the single most effective change you can make.
This is not the same as the 750 GB per-user daily transfer cap, which cannot be raised. See the question about parked runs.
No — not for a year, and never because Google says so. That is the entire point of a backup.
The app notices the deletion and records when the item stopped existing upstream, so you can tell the difference between "this is still in Google" and "this only exists in the backup now". On the live data, roughly 42,000 indexed items no longer exist at source; that history is exactly what a customer is paying for.
After 365 days the backup of a deleted item is removed for good. That window is fixed in the software and is not an operator setting. Until then it is fully restorable.
Deletion is noticed for mail as well as Drive, on every destination. It is not noticed while a listing looks incomplete — a partial or filtered listing, an empty one, or one that would mark more than half an account at once is refused and recorded rather than acted on, because wrongly marking a live item eventually destroys the backup of a file that still exists.
A large binary is downloaded as a single stream. Progress is reported per item, so a 2 GB video looks like a stall until it completes and the counter jumps.
The run is only genuinely stuck if the health indicator stops updating for a long period — that is driven by a separate heartbeat that ticks even when every item is being skipped.
The job is picked up the next time the app starts. It is marked stale, with an explanation recorded against it naming the account it was on, the phase, how many accounts it had finished and how far into the run it stopped.
Nothing that was already backed up is lost, and nothing is duplicated. The next scheduled run is a normal incremental: it walks every account again and skips what is already captured, so accounts the interrupted run never reached are covered then.
If you want it sooner, start a backup by hand rather than waiting for the schedule.
Shared drives are backed up as their own pseudo-accounts and are configured per client. Collaborative inboxes and groups are covered on the admin tier.
They restore the same way as a user account, with one difference: because a shared drive is not a person, restoring it always needs a target account to write into.
Yes, for Drive files. Each backup keeps the previous copy of anything that changed, so a file that has been edited several times has several stored versions. In the file browser a version count appears beside it; open that and you can pick a version by the date it was captured and restore that one. The most recent is selected by default.
You can also roll back in bulk — a whole workspace, one account, or one section such as Drive or Gmail — to how it stood at a chosen backup, rather than as it stands now.
Two limits worth knowing:
Restoring an older version adds it alongside what is in the account now. Nothing live is overwritten or deleted.
Wherever they came from, as far as the app can tell. Every indexed Drive item records its original folder path, and a restore rebuilds that tree in the target.
Two exceptions:
Unfiled inside that container rather than being scattered at the root of someone's Drive.Restoring a single file from the file browser is deliberately different: it goes back exactly where it came from.
Yes — choose a target account in the restore wizard. Everything lands in a folder named after the original account so it is obvious whose data it is.
This is how you handle a leaver: their mail and files go to a manager or an archive account, contained in one folder rather than mixed into that person's own Drive.
Note that restoring into an account counts against that account's 750 GB daily upload cap, not the original owner's.
Yes. A deleted account can always be restored from — its backup is intact and independent of whether the user still exists.
What cannot happen is restoring into it: Google will not issue a token to impersonate an account that is gone. Name an active account as the target and the wizard will put everything there, in a folder named after the deleted user. The preflight check warns you before you start if any account in scope no longer exists.
No. Every item successfully written back is recorded against the restore, so a resume skips what has already been done and continues from there. On the last large live restore that ledger correctly skipped 1,887 already-restored items across three attempts.
One caveat worth knowing: the record is per file, so resuming a partially-processed contacts file can re-create contacts, because the contacts API has no way to say "this one already exists". Calendar events are safe — they are imported with their original identifier, so a repeat updates rather than duplicates.
Not automatically — it is planned for a future release. In the meantime, every cross-account restore puts its items inside a single container folder, so removing them is a matter of deleting that one folder rather than hunting through a Drive.
One thing to do promptly: restored items are new files as far as Google is concerned, so if they are left in place they will be picked up as new content by the next backup, inflating both storage and the index. Clean up test restores before the next scheduled run.
The wizard tells you before you start. It adds up the bytes involved and compares them against Google's 750 GB per-user daily cap, then says how many days to expect and whether it will need to park and resume.
The estimate is a floor, not a ceiling: items backed up before size tracking have no recorded size, so the real figure can be higher. The estimate says so when that applies.
Retention works on the backup, never on the live Workspace. There are two separate things at work.
Your retention policy, set per client, removes backed-up items older than the window you choose and removes their index rows so the space is genuinely reclaimed. Items you have shielded — specific Drive folders or Gmail labels — are exempt and kept regardless of age.
The deleted-item window is fixed at 365 days and cannot be changed by anyone. When something disappears from the customer's Workspace the app records when it went; a year later its backup is removed for good. The object is deleted first and the index row only after the destination confirms it, so a failure leaves the row in place rather than orphaning bytes that nothing points at any more.
Pruning ships switched off. Read the forecast on the retention screen first, then turn it on deliberately — it is the one background job that destroys customer data permanently. Archived clients are exempt entirely: frozen means their deleted items do not age out either.
No. Removing an item also removes its index entry, and the incremental check works from the index — but the retention rule is applied first, so an item that is old enough to be pruned is not re-fetched on the next run.
The exception is an item that has been modified in Google since it was pruned. That is a new version as far as the app is concerned, and it will be backed up again.
For the backup data itself: roughly what the Workspace holds, plus every retained version. Compression and deduplication apply within a run, not across versions.
For the app's own database, measured on a live install: about 940 bytes per indexed item, all-in. Around 800,000 items works out at roughly 600 MB across the two database files. The Database Optimization screen shows the current size and can compact it.
From this release, one console database plus one database per client.
gws-backup.db — the console: your settings, operator accounts, clients and their connection details, schedules, the job log and the audit log. It is small.clients/<clientId>.db — one per client, holding that client's entire backup index. This is almost all of the data: on a five-client install the index was 826,119 of roughly 838,000 rows.gws-backup-archive.db — older installations only. The migration absorbs it and leaves it empty; keep it until you are satisfied, then delete it.They must always travel together. A copy of gws-backup.db alone is your settings and none of your backups. update.php, the console's own database backup and the restore script all handle the whole set.
Splitting per client bounds each client's growth, makes one client's data portable, and takes VACUUM and backup windows from whole-estate to per-client. A new installation starts this way and never needs migrating; an existing one is migrated by running migrate-index-integer-ids.mjs and then split-client-databases.mjs, in that order, with the app stopped.
It is the master key to your backups, not a server setting. Every email body, every calendar and contacts backup is encrypted with it, as is every stored credential — service-account keys, Drive OAuth tokens, S3 and Azure secrets — and every 2FA secret.
If you lose it, that data cannot be recovered by any means. Not by us, not by anyone. It is 32 random bytes and there is no back door.
Keep it in a password manager and somewhere offline, off the server it belongs to, and never stored alongside the backups themselves. You can reveal and download it from Settings → Team & Access Roles; that download is recorded in the audit log.
There is no rotation: nothing re-encrypts existing data, so changing the key orphans everything already stored.
The encryption key, first and above everything else. Put it into the new server's .env *before* the first boot, and certainly before restoring a database.
A fresh install generates its own key. Restore a database on top of that and the console will come up looking perfectly healthy — every client, every setting, every schedule — while nothing encrypted can be read and nothing explains why. The restore checker (restore-console-db.mjs) tests exactly this before it will install anything.
Only the key has to travel. The session secret can be regenerated (it only signs everyone out), and the database path, public URL, port and edition describe one specific server — check them rather than copying them.
Roles take effect immediately. Changing someone's role or resetting their password applies on their very next request rather than whenever their session happens to expire.
Each person enables it for themselves under Settings → My Security — scan the QR code with any authenticator app, confirm one code, and it is on. It applies per account, not per installation.
If someone loses their authenticator, a Super Admin can clear it for them from Team & Access Roles: the account then signs in with its password alone until they set it up again. That reset ends their existing sessions and is recorded in the audit log.
If the only Super Admin loses theirs, the recovery key is the way back in — it clears two-factor authentication as well as resetting the password.
The app never sends email, so there is no "reset my password" link. The recovery key is the substitute: a one-off secret, generated from Team & Access Roles, that resets the administrator password and clears two-factor authentication in one step.
Because it does both, it is enough on its own to get into the account — keep it offline and treat it like the encryption key. Generate one before you need it; an install with no recovery key configured has no password recovery path at all.
A second Super Admin is the other answer, and needs no secret to look after.
Yes. Reading backed-up content is recorded, and there are only two ways to do it:
Both appear flagged in Settings → Activity Log, which can be filtered by action and by date range. Both are restricted to Super Admins and Restore Operators; a Reporter cannot read content at all.
Install it on as many of your own servers as you like, protect as many Google Workspaces as your key allows — ten on the free licence, more by arrangement — and use it commercially, including providing backup services to your own paying clients.
What you may not do is rebrand or re-market it as your own product, resell or redistribute it or its licence keys, remove the GWS Backup or KIKO Solutions branding, or reverse-engineer it. If you want the console and reports to carry your branding alone, that is what the white-label programme is for — get in touch.
Each key permits one running installation at a time. You may move an installation to a different server whenever you like, but the same key must not be live in two places at once — including a staging copy that happens to be running.
Key usage is monitored. If you need failover, clustering or a lab environment, ask rather than running two: it is usually easy to arrange.
Nothing stops. The console keeps working on the licence it already holds and shows a small banner saying the check could not be completed, with a retry.
Licensing will never stand between you and your backups: it only blocks when there is an actual verdict — no key entered, or a key that has genuinely been rejected. A network problem, a missing setting or an error on our side is treated as "unknown" and gets out of the way.
That message means the app found a database with real data in it, but no ENCRYPTION_KEY in the environment. It stops deliberately rather than generating a new key, because a new key would silently orphan every stored credential and make the email, calendar and contacts backups unreadable.
Fix it in this order:
.env file from your safe copy. It must carry the original key.ENCRYPTION_KEY in the hosting panel's environment.The same message is written to STARTUP-BLOCKED.txt in the app folder, for hosts where the console output is hard to reach.
The client's domain-wide delegation does not cover a scope the app is asking for. Google's delegation is all-or-nothing per request: one missing scope fails the whole token exchange, so this shows up as a total failure rather than one missing feature.
Go to the client's Google Admin console → Security → API controls → Domain-wide delegation, find the service account's Client ID, and make sure the scope list matches exactly what the connection wizard shows.
Restores need more scopes than backups — backups are read-only. The restore preflight probes each scope individually and tells you which ones are missing before you commit to a run.
Almost certainly the wrong encryption key. If a database is restored onto a server holding a different ENCRYPTION_KEY, the console starts, you can sign in, and every client, setting and schedule is present — but nothing encrypted can be decrypted, so every connection fails.
Check the key fingerprint shown in Settings → Team & Access Roles against the one recorded in the backup you restored. The app also logs a loud mismatch warning at startup when the key does not match the data.
The answer is always to restore the original key, never to re-enter the credentials — the stored data is still encrypted with the old key.
Settings → Activity Log, which is Super Admin only. It shows every recorded action — backups, restores, destination changes, password and two-factor resets, content access and console database backups — with who did it and when.
It can be filtered by action, by whether the entry is system-level or belongs to a client, by a date range, and by free text across the detail.
For a specific backup run, the client's own screens show per-job detail including any errors recorded against it.
No, and we will keep it that way for as long as we can. Support costs us time rather than money, so it is the last thing we would put behind a price — including for people on the free ten-workspace licence.
First adopters get particular attention. If you took a chance on this before it had any track record, you are the reason it improves, and that earns you more of our time, not less. If a paid support tier ever becomes necessary we will say so plainly and well in advance — it will not appear one morning as a locked door.
Email support@gwsbackup.com with:
Please do not send your .env file, your encryption key or a database copy unless we specifically ask. If we do, we will tell you how to send it safely.
No answers match your search.
Try a different word, or send us your question — good ones end up on this page.